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主要 文档 


Nginx 功 能 概述 


HTTP 基 础 功能 : 


义理 静态 文件 ， 索 引文 件 以 及 自动 索引 ; 

反 向 代理 加 速 (无 缓存 )， 简 单 的 负载 均衡 和 容错 ; 

FastCGI， 简 单 的 负载 均衡 和 容错 ; 

模块 化 的 结构 。 过 滤器 包括 gzipping, byte ranges, chunked responses, 以 及 SSl-filter 。 
在 SSI 过 滤器 中 ， 到 同一 个 proxy 或 者 FastCGI 的 多 个 子 请 求 并 发 处 理 ; 

SSL 和 TLS SNI 支持 ; 


IMAP/POP3 代理 服务 功能 : 


使 用 外 部 HTTP 认证 服务 器 重 定向 用 户 到 IMAP/POP3 后 端 ; 

使 用 外 部 HTTP 认证 服务 器 认证 用 户 后 连接 重 定向 到 内 部 的 SMTP 后 端 ; 
认证 方法 : 

POP3: POP3 USER/PASS, APOP, AUTH LOGIN PLAIN CRAM-MD5; 
IMAP: IMAP LOGIN; 

SMTP: AUTH LOGIN PLAIN CRAM-MD5; 

SSL 支持 ; 

在 IMAP 和 POP3 模式 下 的 STARTTLS 和 STLS 支持 ; 


支持 的 操作 系统 : 


FreeBSD 3.x, 4.x, 5.x, 6.x i386; FreeBSD 5.x, 6.x amd64; 
Linux 2.2, 2.4, 2.6 i386; Linux 2.6 amd64; 

Solaris 8 i386; Solaris 9 i386 and sun4u; Solaris 10 i386; 
MacOS X (10.4) PPC; 


结构 与 扩展 : 


一 个 主 进程 和 多 个 工作 进程 。 工 作 进 程 是 单线 程 的 ， 且 不 需要 特殊 授权 即 可 运行 ; 
kqueue (FreeBSD 4.1+), epoll (Linux 2.6+), rt signals (Linux 2.2.19+), /dev/poll (Solaris 
7 11/99+), select, 以 及 poll 支持 ; 

kqueue 支 持 的 不 同 功能 包括 EV CLEAR, EV DISABLE (临时 禁止 事件 ) ， 

NOTE LOWAT, EV_EOF, 有 效 数据 的 数目 ， 错 误 代码 ; 

sendfile (FreeBSD 3.1+), sendfile (Linux 2.2+), sendfile64 (Linux 2.4.21+), 和 sendfilev 
(Solaris 8 7/01+) 支持 ; 

输入 过 滤 (FreeBSD 4.1+) LA TCP_DEFER_ACCEPT (Linux 2.4+) 支持 ; 

10,000 非 活动 的 HTTP keep-alive 连接 仅 需要 2.5M 内 存 。 

最 小 化 的 数据 拷贝 操作 ; 


其 他 HTTP 功 能 : 


基于 IP 和 名 称 的 虚拟 主机 服务 ; 

e Memcached 的 GET 接口 ; 

。 支持 keep-alive 和 管道 连接 ; 

灵活 简单 的 配置 ; 

重新 配置 和 在 线 升 级 而 无 须 中 断 客户 的 工作 进程 ; 
e 可 定制 的 访问 日 志 ， 日 志 写 入 缓存 ， 以 及 快捷 的 日 志 回 卷 ; 
e 4xx-5xx 错误 代码 重 定向 ; 

基于 PCRE 的 rewrite 重 写 模 块 ; 

e 基于 客户 端 IP 地 址 和 HTTP 基本 认证 的 访问 控制 ; 
PUT, DELETE, 和 MKCOL 方法 ; 

支持 FLV (Flash 视频 ) ; 

e 带宽 限制 ; 


实验 特性 : 


e AR perl 
e 通过 aio read() / aio write() 的 套 接 字 工 作 的 实验 模块 ， 仅 在 FreeBSD 下 。 
e 对 线程 的 实验 化 支持 ，FreeBSD 4.x 的 实现 基于 rfork() 


Nginx 主要 的 英语 站 点 是 http://sysoev.ru/en/ 


英语 文档 草稿 由 Aleksandar Lazic 完成 点 击 。 


为 什么 选择 Nginx 
Nginx 是 一 个 高 性 能 的 Web 和 反 向 代理 服务 器 , 它 具有 有 很 多 非常 优越 的 特性 : 


作为 Web 服务 器 : THEE Apache, Nginx 使 用 更 少 的 资源 ， 支 持 更 多 的 并 发 连接 ， 体 现 更 高 
的 效率 ， 这 点 使 Nginx 尤其 受到 虚拟 主机 提供 商 的 欢迎 。 能 够 支持 高 达 50,000 个 并 发 连接 数 
的 响应 ， 感 谢 Nginx 为 我 们 选择 了 epoll and kqueue 作为 开发 模型 . 


作为 负载 均衡 服务 器 : Nginx 既 可 以 在 内 部 直接 支持 Rails 和 PHP， 也 可 以 支持 作为 HTTP 代 
理 服务 器 对 外 进行 服务 。Nginx A C 编写 , 不 论 是 系统 资源 开销 还 是 CPU 使 用 效率 都 比 
Perlbal 要 好 的 多 。 

作为 邮件 代理 服务 器 : Nginx 同时 也 是 一 个 非常 优秀 的 邮件 代理 服务 器 (最 早 开发 这 个 产品 的 
目的 之 一 也 是 作为 邮件 代理 服务 器 ) , Last.fm 描述 了 成 功 并 且 美 妙 的 使 用 经 验 。 

Nginx 安装 非常 的 简单 ， 配 置 文件 非常 简洁 (还 能 够 支持 perl 语 法 ) ，Bugs 非 常 少 的 服务 器 : 
Nginx 启动 特别 容易 ， 并 且 几 乎 可 以 做 到 7*24 不 间断 运行 ， 即 使 运行 数 个 月 也 不 需要 重新 启 
动 。 你 还 能 够 在 不 间断 服务 的 情况 下 进行 软件 版 本 的 升级 。 


Nginx 安 装 


nginx 可 以 使 用 各 平台 的 默认 包 来 安装 ， 本 文 是 介绍 使 用 源码 编译 安装 ， 包 括 具 体 的 编译 参数 
信息 。 


正式 开始 前 ， 编 译 环境 gcc g++ 开发 库 之 类 的 需要 提前 装 好 ， 这 里 默认 你 已 经 装 好 。 


ububtu 平 台 编 译 环境 可 以 使 用 以 下 指 兮 


apt-get install build-essential 
apt-get install libtool 


centos 平 台 编 译 环境 使 用 如 下 指 今 


安装 make : 
yum -y install gcc automake autoconf libtool make 
安装 g++: 


yum install gcc gcc-c++ 


下 面 正式 开始 


一 般 我 们 都 需要 先 装 pcre, zlib, HAA T BSrewrite, BAH T gzip zz. 
1. 选 定 源码 目录 
可 以 是 任何 目录 ， 本 文选 定 的 是 /usr/local/src 


cd /usr/local/src 
2. 安 装 PCRE 库 


ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/ 下 载 最 新 的 PCRE 源码 包 ， 使 用 下 面 
命令 下 载 编译 和 安装 PCRE S: 


cd /usr/local/src 

wget ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/pcre-8.34.tar.gz 
tar -zxvf pcre-8.34.tar.gz 

cd pcre-8.34 

./configure 

make 

make install 


3. 安 装 zlib 库 
http://zlib.net/zlib-1.2.8.tar.gz 下 载 最 新 的 zlib 源码 包 ， 使 用 下 面 命令 下 载 编译 和 安装 zlib 包 : 


cd /usr/local/src 


wget http://zlib.net/zlib-1.2.8.tar.gz 
tar -zxvf zlib-1.2.8.tar.gz 

cd zlib-1.2.8 

./configure 

make 

make install 


4. 安 装 ssl ( 某 些 vps 默 认 没 装 ssl) 


cd /usr/local/src 
wget http://www.openssl.org/source/openssl-1.0.1c.tar.gz 
tar -zxvf openssl-1.0.1c.tar.gz 


5. 安 装 nginx 


Nginx 一 般 有 两 个 版 本 ， 分 别 是 稳定 版 和 开发 版 ， 您 可 以 根据 您 的 目的 来 选择 这 两 个 版 本 的 其 
中 一 个 ， 下 面 是 把 Nginx 安装 到 /usr/local/nginx 目录 下 的 详细 步骤 : 


cd /usr/local/src 

wget http://nginx.org/download/nginx-1.4.2.tar.gz 
tar -zxvf nginx-1.4.2.tar.gz 

cd nginx-1.4.2 


./configure --sbin-path=/usr/local/nginx/nginx \ 
--conf-path-/usr/local/nginx/nginx.conf \ 
--pid-path-/usr/local/nginx/nginx.pid \ 
--with-http_ssl_module \ 
--with-pcre=/usr/local/src/pcre-8.34 \ 
--with-zlib=/usr/local/src/zlib-1.2.8 \ 
--with-openssl-/usr/local/src/openssl-1.0.1c 


make 
make install 


--with-pcre=/usr/src/pcre-8.34 指 的 是 pcre-8.34 的 源码 路 径 。 
--with-zlib=/usr/src/zlib-1.2.7 指 的 是 zlib-1.2.7 的 源码 路 径 。 


安装 成 功 后 /usr/local/nginx 目录 下 如 下 


fastcgi.conf koi-win nginx.conf.default 


fastcgi.conf.default logs scgi params 
fastcgi params mime.types scgi params.default 
fastcgi params.default  mime.types.default  uwsgi params 
html nginx uwsgi params.default 
koi-utf nginx.conf win-utf 

6.8 5b 


确保 系统 的 80 端口 没 被 其 他 程序 占用 ， 运 行 /usr/local/nginx/nginx 命令 来 启动 Nginx， 


netstat -ano|grep 80 


mo 


如 果 查 不 到 结果 后 执行 ， 有 结果 则 忽略 此 步骤 (ubuntu 下 必须 用 sudo 启 动 ， 不 然 只 能 在 前 台 
行 


) 


B 


sudo /usr/local/nginx/nginx 


打开 浏览 器 访问 此 机 器 的 IP， 如 果 浏 览 器 出 现 Welcome to nginx! 则 表示 Nginx 已 经 安装 并 
运行 成 功 。 
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Welcome to nginx! 


到 这 里 nginx 就 安装 完成 了 ， 如 果 只 是 义理 静态 html 就 不 用 继续 安装 了 
如 果 你 需要 人 处理 php 脚 本 的 话 ， 还 需要 安装 php-fpm。 

面 安装 排 错 
附 : 可 能 遇 到 的 错误 和 一 些 帮助 信息 


1.1 编 译 pcre 错 误 


libtool: compile: unrecognized option '-DHAVE CONFIG H' 
libtool: compile: Try “libtool --help' for more information. 
make[1]: *** [pcrecpp.lo] Error 1 

make[1]: Leaving directory ~/usr/local/src/pcre-8.34' 

make: *** [all] Error 2 


ile: unrecognized option '-DHAVE CONFIG K' 





解决 办 法 : 安装 g++, 别 忘 了 重新 configure 


apt-get install g++ 

apt-get install build-essential 
make clean 

./configure 

make 


1.2 make 出 错 


make: *** No rule to make target ‘build', needed by "default'. Stop. 
./configure: error: SSL modules require the OpenSSL library. 

You can either do not enable the modules, or install the OpenSSL library 
into the system, or build the OpenSSL library statically from the source 
with nginx by using --with-openssl- 


option. 


按照 第 4 步 的 安装 方法 或 
ubuntu 下 


apt-get install openssl 
apt-get install libssl-dev 


centos F 


yum -y install openssl openssl-devel 


2.nginx 编 译 选 项 
make 是 用 来 编译 的 ， 它 从 Makefile 中 读 取 指 令 ， 然 后 编译 。 
make install 是 用 来 安装 的 ， 它 也 从 Makefile 中 读 取 指 令 ， 安 装 到 指定 的 位 置 。 


configure 命 令 是 用 来 检测 你 的 安装 平台 的 目标 特征 的 。 它 定义 了 系统 的 各 个 方面 ， 包 括 nginx 
的 被 允许 使 用 的 连接 处 理 的 方法 ， 上 比如 它 会 检测 你 是 不 是 有 CC 或 G6CC， 并 不 是 需要 CC 或 
GCC， 它 是 个 shell 脚 本 ， 执 行 结 束 时 ， 它 会 创建 一 个 Makefile 文 件 。nginx 的 configure 命 合 支 
持 以 下 参数 : 


e -.prefix- path 定义 一 个 目录 ， 存 放 服 务 器 上 的 文件 ， 也 就 是 nginx 的 安装 目录 。 默 认 使 
用 /usr/local/nginx. 

e --sbin-path- path 设置 nginx 的 可 执行 文件 的 路 径 ， 默 认为 `*prefix* /sbin/nginx’. 

e --conf-path= path 设置 在 nginx.conf 配 置 文件 的 路 径 。nginx 人 允许 使 用 不 同 的 配置 文件 启 
动 ， 通 过 命令 行 中 的 -c 选 项 。 默 认为 `*prefix* /conf/nginx.conf . 

e --pid-path= path 设置 nginx.pid 文 件 ， 将 存储 的 主 进程 的 进程 号 。 安 装 完成 后 ， 可 以 随 
时 改变 的 文件 名 ， 在 nginx.conf 配 置 文件 中 使 用 PID 指 令 。 黑 认 情 况 下 ， 文 件 名 
为 `*prefix* /logs/nginx.pid'. 

èe --error-log-path= path 设置 主 错误 ， 警 告 ， 和 诊断 文件 的 名 称 。 安 装 完成 后 ， 可 以 随时 
改变 的 文件 名 ， 在 nginx.conf 配 置 文件 中 使 用 的 error log 指令 。 黑 认 情 况 下 ， 文 件 名 
为 `*prefix* /logs/errorlog . 

e --http-log-path= path 设置 主 请 求 的 HTTP 服 务 器 的 日 志文 件 的 名 称 。 安 装 完成 后 ， 可 以 
随时 改变 的 文件 名 ， 在 nginx.conf 配 置 文件 中 使 用 access log 指令。 默认 情况 下 ， 文 
件 名 4 ^*prefix* /logs/access.log `. 

e --user- name 设置 nginx 工 作 进程 的 用 户 。 安 装 完成 后 ， 可 以 随时 更 改 的 名 称 在 
nginx.conf 配 置 文件 中 使 用 的 user 指 令 。 默 认 的 用 户 名 是 nobody。 

e --group= name 设置 nginx 工 作 进 程 的 用 户 组 。 安 装 完成 后 ， 可 以 随时 更 改 的 名 称 在 
nginx.conf 配 置 文件 中 使 用 的 user 指 邻 。 软 认 的 为 非特 权 用 户 。 

e  --with-select module '--without-select module 和 启用 或 禁用 构建 一 个 模块 来 允许 服务 器 使 用 select( ) 

e --with-poll_module、--without-poll_module 和 启用 或 禁用 构建 一 个 模块 来 允许 服务 器 使 用 
poll() 方 法 。 该 模块 将 自动 建立 ， 如 果 平台 不 支持 的 kqueue，epoll，rtsig 或 /dev/poll。 

e --without-http_gzip_module 一 不 编译 压缩 的 HTTP 服 务 器 的 响应 模块 。 编 译 并 运行 此 模 
块 需要 zlib 库 。 

e --without-http_rewrite_module 不 编译 重 写 模 块 。 编译 并 运行 此 模块 需要 PCRE 库 支 
持 。 

e --without-http_proxy_module 一 不 编译 http_proxy 模 块 。 

e --with-http_ssl_module 一 使 用 https 协 议 模 块 。 默 认 情 况 下 ， 该 模块 没有 被 构建 。 建 立 


并 运行 此 模块 的 OpenSSL 库 是 必需 的 。 

e --with-pcre= path 一 设置 PCRE 库 的 源码 路 径 。PCRE 库 的 源码 (版 本 4.4 - 8.30) 需要 
从 PCRE 网 站 下 载 并 解压 。 其 余 的 工作 是 Nginx 的 ./ configure 和 make 来 完成 。 正 则 表达 式 
使 用 在 location 指 令 和 ngx http rewrite module 模块 中 。 

e --with-pcre-jit —#4j#PCRE@S ‘just-in-time compilation”(1.1.12 中 ， pcre _jit 指 


D)o 


e --with-zlib- path 一 设置 的 zlib 库 的 源码 路 径 。 要 下 载 从 zlib (版 本 1.1.3 - 1.2.5) 的 并 
解压 。 其 余 的 工作 是 Nginx 的 ./ configure 和 make 完 成 。ngx_http_gzip_module 模 块 需要 
使 用 zlib 。 

e --with-cc-opt= parameters 一 设置 额外 的 参数 将 被 添加 到 CFLAGS 变 量 。 例 如 , 当 你 在 
FreeBSD 上 使 用 PCRE 库 时 需要 使 用 : - -with-cc-opt="-I /usr/local/include, .如 需要 需 
要 增加 select( ) 支 持 的 文件 数量 | - -with-cc-opt="-D FD SETSIZE-2048". 

e --with-1d-opt- parameters 一 设置 附加 的 参数 ， 将 用 于 在 链接 期 间 。 例 如 ， 当 在 
FreeBSD 下 使 用 该 系统 的 PCRE 库 ,应 指定 : --with-1d-opt="-L /usr/local/lib". 


典型 实例 (下 面 为 了 展示 需要 写 在 多 行 ， 执 行 时 内 容 需 要 在 同一 行 ) 


./configure 
--sbin-path=/usr/local/nginx/nginx 
--conf -path=/usr/local/nginx/nginx.conf 
--pid-path=/usr/local/nginx/nginx.pid 
--with-http ssl module 
--with-pcre=../pcre-4.4 
--with-zlib=../zlib-1.1.3 


运行 和 控制 Nginx 
nginx 命 信行 参 数 
不 像 许 多 其 他 软件 系统 ，Nginx 仅 有 几 个 命令 行 参 数 ， 完 全 通过 配置 文件 来 配置 


-c </path/to/config> 为 Nginx 指定 一 个 配置 文件 ， 来 代替 缺 省 的 。 


-t 不 运行 ， 而 仅仅 测试 配置 文件 。nginx 将 检查 配置 文件 的 语法 的 正确 性 ， 并 党 试 打开 配置 文 
件 中 所 引用 到 的 文件 。 


-v 显示 nginx 的 版 本 。 


-V 显示 nginx 的 版 本 ， 编 译 器 版 本 和 配置 参数 。 


nginx 控 制 信 号 


可 以 使 用 信号 系统 来 控制 主 进程 。 默 认 ，nginx 将 其 主 进程 的 pid SAB 
lusr/local/nginx/nginx.pid 文件 中 。 通 过 传递 参数 给 ./configure 或 使 用 pid 指令 ， 来 改变 该 文 
件 的 位 置 。 


主 进程 可 以 处 理 以 下 的 信号 : 


TERM, INT 快速 关闭 

QUIT 从 容 关 闭 
重 载 配 置 

HUP 用 新 的 配置 开始 新 的 工作 进程 
从 容 关 闭 旧 的 工作 进程 

USR1 重新 打开 日 志文 件 

USR2 平滑 升级 可 执行 程序 。 

WINCH 从 容 关 闭 工 作 进 程 


尽管 你 不 必 自 己 操作 工作 进程 ， 但 是 ， 它 们 也 支持 一 些 信号 : 


TERM, INT 快速 关闭 
QUIT 从 容 关 闭 
USR1 重新 打开 日 志文 件 


nginx 6a), (Fil, Bema 


nginx £ zj 


sudo /usr/local/nginx/nginx (nginx 二 进 制 文件 绝对 路 径 ， 可 以 根据 自己 安装 路 径 实际 决定 ) 
nginx 从 容 停止 命 售 ， 等 所 有 请 求 结束 后 关闭 服务 

ps -ef |grep nginx 

kill -QUIT nginx 主 进程 号 

nginx 快速 停止 命 舍 ， 立 刻 关闭 nginx 进 程 

ps -ef |grep nginx 

kill -TERM nginx 主 进程 号 

如 果 以 上 命令 不 管用 ， 可 以 强制 停止 

kill -9 nginx 主 进程 号 


如 果 嫌 麻烦 可 以 不 用 查看 进程 号 ， 直 接 使 用 命 人 进行 操作 

其 中 /usr/local/nginx/nginx.pid 为 nginx.conf 中 pid 命 令 设 置 的 参数 ， 用 来 存放 nginx 主 进程 号 的 
文件 

kill -信号 类 型 (HUPITERMIQUIT) cat /usr/1ocal/nginx/nginx.pid 

例如 


kill -QUIT ‘cat /usr/local/nginx/nginx.pid^ 


nginx 重 启 命令 
nginx 重 启 可 以 分 成 几 种 类 型 
1. 简 单 型 ， 先 关闭 进程 ， 修 改 你 的 配置 后 ， 重 启 进程 。 


kill -QUIT cat /usr/local/nginx/nginx.pid 

sudo /usr/local/nginx/nginx 

2. 重 新 加 载 配置 文件 ， 不 重启 进程 ， 不 会 停止 处 理 请 求 
3. 平 滑 更 新 nginx 二 进 制 ， 不 会 停止 处 理 请 求 


使 用 信号 加 载 新 的 配置 


Nginx 支持 几 个 信号 ， 能 在 它 运 行 时 控制 其 操作 。 其 中 最 普通 的 是 15 ， 用 来 中 止 运 行 的 进 
程 : 


# <strong>ps aux | egrep '(PID|nginx)'</strong> 

USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND 

root 2213 0.0 0.0 6784 2036 ? Ss 03:01 0:00 nginx: master process /u 
# <strong>kill -15 2213</strong> 


: = 








而 最 有 趣 的 是 能 平滑 改变 nginx 配置 的 选项 〈 请 注意 ， 在 重 载 前 ， 要 先 测试 一 下 配置 文 
件 ) 


#<strong> nginx -t -c /etc/nginx/nginx.conf</strong> 


2006/09/16 13:07:10 [info] 15686#0: the configuration file /etc/nginx/nginx.conf syntax i 
2006/09/16 13:07:10 [info] 15686#0: the configuration file /etc/nginx/nginx.conf was test 


#<strong> ps aux | egrep '(PID|nginx)'</strong> 
USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND 


root 2213 0.0 0.0 6784 2036 ? Ss 03:01 0:00 nginx: master process /u 


<strong># kill -HUP 2213</strong> 


4 


“4 nginx 接收 到 HUP 信号 ， 它 会 尝试 先 解析 配置 文件 〈 如 果 指 定 配置 文件 ， 就 使 用 指定 的 ， 
否则 使 用 默认 的 ) ， 成 功 的 话 ， 就 应 用 新 的 配置 文件 (例如 : 重新 打开 日 志文 件 或 监听 的 套 
接 字 ) 。 之 后 ，nginx 运行 新 的 工作 进程 并 从 容 关 闭 旧 的 工作 进程 。 通 知 工作 进程 关闭 监听 
套 接 字 但 是 继续 为 当前 连接 的 客户 提供 服务 。 所 有 客户 端的 服务 完成 后 ， 旧 的 工作 进程 被 关 
Hj. 如 果 新 的 配置 文件 应 用 失败 ，nginx 将 继续 使 用 旧 的 配置 进行 工作 。 








平滑 升级 到 新 的 二 进 制 代码 


你 可 以 在 不 中 断 服 务 的 情况 下 - 新 的 请 求 也 不 会 去 失 ， 使 用 新 的 nginx 可 执行 程序 替换 旧 的 
( 当 升 级 新 版 本 或 添加 /删除 服务 器 模块 时 ) 。 


首先 ， 使 用 新 的 可 执行 程序 替换 旧 的 〈 最 好 做 好 各 份 ) ， 然 后 ， 发 送 USR2 (kill -USR2 pid) 
信号 给 主 进 程 。 主 进程 将 重 命名 它 的 .pid 文件 为 .oldbin (tb 

如 : /usr/local/nginx/logs/nginx.pid.oldbin)， 然 后 执行 新 的 可 执行 程序 ， 依 次 启动 新 的 主 
进程 和 新 的 工作 进程 : 


PID PPID USER %CPU VSZ WCHAN COMMAND 
33126 1 root 9. 1164 pause nginx: master process /usr/local/nginx/sbin/nginx 
33134 33126 nobody 0 1368 kqread nginx: worker process (nginx) 
33135 33126 nobody 0 1380 kqread nginx: worker process (nginx) 
33136 33126 nobody © 1368 kqread nginx: worker process (nginx) 
36264 33126 root 9. 1148 pause nginx: master process /usr/local/nginx/sbin/nginx 
36265 36264 nobody 0 1364 kqread nginx: worker process (nginx) 
36266 36264 nobody 0 1364 kqread nginx: worker process (nginx) 
36267 36264 nobody 0 1364 kqread nginx: worker process (nginx) 


_ ————————— Á—XÁ——À"um | 


OOOOOOOO 


在 这 时 ， 两 个 nginx 实例 会 同时 运行 ， 一 起 处 理 输 入 的 请 求 。 要 逐步 停止 旧 的 实例 ， 你 必须 
发 送 WINCH 信号 给 旧 的 主 进程 ， 然 后 ， 它 的 工作 进程 就 将 开始 从 容 关 闭 : 


PID PPID USER %CPU VSZ WCHAN COMMAND 
33126 1 root 9. 1164 pause nginx: master process /usr/local/nginx/sbin/nginx 
33135 33126 nobody 1380 kqread nginx: worker process is shutting down (nginx) 
36264 33126 root 1148 pause nginx: master process /usr/local/nginx/sbin/nginx 
36265 36264 nobody 1364 kqread nginx: worker process (nginx) 
36266 36264 nobody 1364 kqread nginx: worker process (nginx) 
36267 36264 nobody 1364 kqread nginx: worker process (nginx) 


O0O000 
OOOOOO 








一 段 时 间 后 ， 旧 的 工作 进程 处 理 了 所 有 已 连接 的 请 求 后 退出 ， 就 仅 由 新 的 工作 进程 来 处 理 输 
入 的 请 求 了 : 


PID PPID USER %CPU VSZ WCHAN COMMAND 
33126 1 root 0.0 1164 pause nginx: master process /usr/local/nginx/sbin/nginx 
36264 33126 root 1148 pause nginx: master process /usr/local/nginx/sbin/nginx 
36265 36264 nobody 1364 kqread nginx: worker process (nginx) 
36266 36264 nobody 1364 kqread nginx: worker process (nginx) 
36267 36264 nobody 1364 kqread nginx: worker process (nginx) 


‘| ae n 


这 时 ， 因 为 旧 的 服务 器 还 尚未 关闭 它 监听 的 套 接 字 ， 所 以 ， 通 过 下 面 的 几 步 ， 你 仍 可 以 恢复 
旧 的 服务 器 : 





。 发 送 HUP 信号 给 旧 的 主 进程 - 它 将 在 不 重 载 配置 文件 的 情况 下 启动 它 的 工作 进程 
。 发 送 QUIT 信号 给 新 的 主 进程 ， 要 求 其 从 容 关 闭 其 工作 进程 

e 发 送 TERM 信号 给 新 的 主 进程 ， 迫 使 其 退出 

。 如 果 因 为 某 些 原因 新 的 工作 进程 不 能 退出 ， 向 其 发 送 KILL 信号 


新 的 主 进程 退出 后 ， 旧 的 主 进程 会 由 移 除 .oldbin 前 级 ， 恢 复 为 它 的 .pid 文件 ， 这 样 ， 一 切 
就 都 恢复 到 升级 之 前 了 。 


如 果 尝 试 升级 成 功 ， 而 你 也 希望 保留 新 的 服务 器 时 ， 发 送 QUT 信号 给 旧 的 主 进程 使 其 退出 而 
只 留 下 新 的 服务 器 运行 


PID PPID USER %CPU VSZ WCHAN COMMAND 
36264 1 root 0.0 1148 pause nginx: master process /usr/local/nginx/sbin/ngi 
36265 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) 
36266 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) 
36267 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) 





m,M 兆 字 节 
例如 , "Sk", "1m" 代表 字 节 数 计量 . 


时 间 符 号 缩写 


ms 

S 秒 

m 分 钟 

h 小 时 

d 日 

w 周 

M = nay ore 
y 年 , 365 X 


例如 , "1h 30m", "ty 6M". 代表 "1 小 时 302", "1E BETA". 


dt 


优化 Nginx 
Ngnix 使 用 hash 表 来 协助 完成 请 求 的 快速 处 理 。 


考虑 到 保存 键 及 其 值 的 hash 表 存储 单元 的 大 小 不 至 于 超出 设 定 参数 (hash bucket size), Æ 
动 和 每 次 重新 配置 时 ，Nginx 为 hash 表 选择 尽 可 能 小 的 尺寸 。 


直到 hash 表 超过 参数 (hash max size) 的 大 小 才 重 新 进行 选择 . 对 于 大 多 数 hash 表 都 有 指令 
修改 这 些 参 数 。 例 如 ， 保 存 服务 器 名 字 的 hash 表 是 由 指令 server names hash max size 和 
server names hash bucket size 所 控制 的 。 参 数 hash bucket size 总 是 等 于 hash 表 的 大 小 ， 并 
且 是 一 路 处 理 器 缓存 大 小 的 倍数 。 在 减少 了 在 内 存 中 的 存 取 次 数 后 ， 使 在 处 理 器 中 加 速 查找 
hash 表 键 值 成 为 可 能 。 如 果 hash bucket size 等 于 一 路 处 理 器 缓存 的 大 小 ， 那 么 在 查找 键 的 时 
候 ， 最 坏 的 情况 下 在 内 存 中 查找 的 次 数 为 2。 第 一 次 是 确定 存储 单元 的 地 址 ， 第 二 次 是 在 存储 
单元 中 查找 键 值 。 因 此 ， 如 果 Nginx 给 出 需要 增 大 hash max size 或 hash bucket size 的 提 
示 ， 那 么 首要 的 是 增 大 前 一 个 参数 的 大 小 . 


事件 模型 


Nginx 支 持 如 下 处 理 连接 的 方法 (I/O 复 用 方法 ) ， 这 些 方 法 可 以 通过 use DE. 








。 select - 标准 方法 。 如 果 当 前 平台 没有 更 有 效 的 方法 ， 它 是 编译 时 默认 的 方法 。 你 可 以 
使 用 配置 参数 --with-select_module 和 --without-select_module 来 启用 或 禁用 这 个 模 
块 。 

poll- 标准 方法 。 如 果 当 前 平台 没有 更 有 效 的 方法 ， 它 是 编译 时 默认 的 方法 。 你 可 以 使 
用 配置 参数 --with-poll module 和 --without-poll module 来 启用 或 禁用 这 个 模块 。 

e kqueue - 高 效 的 方法 ， 使 用 于 FreeBSD 4.1+, OpenBSD 2.9+, NetBSD 2.0 和 MacOS 
X. 使 用 双 处 理 器 的 MacOS X 系 统 使 用 kqueue 可 能 会 造成 内 核 朋 演 。 

epoll - 高 效 的 方法 ， 使 用 于 Linux 内 核 2.6 版 本 及 以 后 的 系统 。 在 某 些 发 行 版 本 中 ， 如 
SuSE 8.2, 有 让 2.4 版 本 的 内 核 支持 epoll 的 补丁 。 

e rtsig - 可 执行 的 实时 信号 ， 使 用 于 Linux 内 核 版 本 2.2.19 以 后 的 系统 。 默 认 情 况 下 整个 系 
统 中 不 能 出 现 大 于 1024 个 POSIX 实 时 (排队 ) 信 号 。 这 种 情况 对 于 高 负载 的 服务 器 来 说 是 
低 效 的 ; 所 以 有 必要 通过 调节 内 核 参 数 /proc/sys/kernel/rtsig-max 来 增加 队列 的 大 
小 。 可 是 从 Linux 内 核 版 本 2.6.6-mm2 开 始 ， 这 个 参数 就 不 再 使 用 了 ， 并 且 对 于 每 个 进程 
有 一 个 独立 的 信号 队列 ， 这 个 队列 的 大 小 可 以 用 RLIMIT_SIGPENDING 参数 调节 。 当 这 
个 队列 过 于 拥塞 ，nginx 就 放弃 它 并 且 开 始 使 用 poii 方法 来 处 理 连接 直到 恢复 正常 。 
Idev/poll - 高 效 的 方法 ， 使 用 于 Solaris 7 11/99+, HP/UX 11.22+ (eventport), IRIX 
6.5.15+ 和 Tru64 UNIX 5.1A+. 

eventport - 高 效 的 方法 ， 使 用 于 Solaris 10. 2; TRILW AKA, BUYER 
装 这 个 安全 补丁 。 


Nginx 中 文官 方 文档 


Hash 表 原始 文档 


优化 Nginx 
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= J i] (FAQ) 


e [#notwork 某 些 东 东 不 工作 (URL, KE, HE, ...)] 

e Hother 有 没有 其 它 类 似 的 Web 服 务 器 ] 

e [#chroot 对 于 chroot 的 支持 是 否 在 计划 之 中 ?] 

e [#usecase 在 什么 情况 下 使 用 Nginx 比 使 用 squid 要 好 ?] 

e [#imapexample 有 没有 人 能 给 出 一 个 完整 的 .conf 配 置 文件 来 详细 的 解读 一 下 怎么 配置 和 
测试 IMAP 模块 ， 而 不 只 是 关于 IMAP 的 只 言 片 语 啊 ?] 

e [#smtpexample 怎么 让 Nginx 成 为 以 postfix 做 为 后 端的 SMTP 代 理 ?] 

e [#loadbalancing Nginx 使 用 什么 算法 来 实现 负载 均衡 ? 它 能 实现 基于 连接 数 的 负载 均衡 
吗 ?] 

e [#proxy_buffering 我 能 关闭 从 代理 服务 器 到 后 端 服 务 器 的 缓存 吗 或 者 使 用 上 传 进 度 特性 ?] 


某 些 东 东 不 工作 (URL 重 写 , 代理 , 路 径 ，.…) 


例如 : 如 URL 重 写 (rewrite) 不 工作 了 或 者 是 unix 的 路 径 (/$PATH) 的 问题 云云 … 





请 仔细 阅读 [NginxDebugging] 并 且 逐 行 查看 错误 日 志 。 
如 果 你 没 找到 错误 打 起 精神 试 着 到 IRC 或 邮件 列表 里 说 明 一 下 你 碰 到 的 问题 。 
有 没有 其 它 类 似 的 Web 服 务 器 


e Cherokee 
e Lighttpd (Lighty) 
e thttpd 


关于 各 自 的 优 缺 点 请 使 用 自己 喜欢 的 搜索 引 划 查找 ;-) 


对 于 chroot 的 支持 是 否 在 计划 之 中 ? 


有 人 知道 吗 ? 


在 什么 情况 下 使 用 Nginx 比 使 用 squid 要 好 ?3 反之 亦 然 。 


大 体 上 来 说 nginx 主 要 用 于 反 向 加 速 代理 而 不 是 像 squid 那 样 做 为 常规 代理 服务 器 。Nginx 的 最 
大 优势 在 于 高 负载 情况 下 内 存 和 CPU 的 低 消耗 。 我 不 认为 squid 能 给 你 带 来 比 nginx 更 好 的 性 
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怎么 让 Nginx 成 为 以 postfix 做 为 后 端的 SMTP 代 理 ? 


有 人 知道 不 ? 


Nginx 使 用 什么 算法 来 实现 负载 均衡 ? 它 能 实现 基于 连接 数 的 负 
载 均 衡 吗 ? 


目前 Nginx 使 用 简单 的 轮 巡 算 法 ， 所 以 无 法 做 基本 链接 计数 的 负载 均衡 。 这 个 可 能 会 在 将 来 的 
版 本 中 有 所 改变 。 


> 我 能 关闭 从 代理 服务 器 到 后 端 服务 器 的 缓存 吗 或 者 使 用 上 传 进 
度 特性 ? 


基于 太 多 人 询问 下 面 的 问题 : 





e 我 能 为 了 得 到 上 传 进度 而 关闭 代理 的 缓存 吗 
。 使 用 nginx 我 怎么 才能 给 用 户 显示 上 传 进度 


到 目前 为 止 (2007-Apr-26) 还 没有 办 法 关闭 到 后 端 服务 器 的 缓存 . 


调试 nginx 
Nginx 的 一 个 杀手 级 特性 就 是 你 能 使 用 debug connection 指令 只 调试 某 些 连接 。 


这 个 设置 只 有 是 你 使 用 --with-debug 编译 的 nginx 才 有 效 。 


AX SE ah" 


Nginx 主 模块 

这 里 是 控制 Nginx 的 基本 功能 的 指 今 . 
bA 
E T 


e [#daemon daemon] 

e [#debug_points debug_points] 

e [#error_log error_log] 

e [#include include] 

e [flock file lock file] 

e [£master process master process] 

e [#pid pid] 

e [£ss| engine ssl engine] 

e [#timer_resolution timer resolution] 

e [#user user group] 

e [£worker cpu affinity worker cpu affinity] 
e [£worker priority worker priority] 

e [#worker processes worker processes] 

e [#worker_rlimit_core worker rlimit core] 
e [#worker_rlimit_nofile worker rlimit nofile] 
e [f£worker rlimit sigpending worker rlimit sigpending] 
e [f£working directory working directory] 


daemon 
语法 :*daemon on | off* 


缺 省 值 :*on* 
daemon off; 


Do not use the "daemon" and "master_process" directives in a production mode, these 
options are mainly used for development only. You can use daemon off safely in production 
mode with runit / daemontools however you can't do a graceful upgrade. 

master process off Should never be used in production. 


生产 环境 中 不 要 使 用 "daemon" 和 "master_process" 指 令 ， 这 些 选项 仅 用 于 开发 调试 。 


debug_points 


i&ik:*debug points [stop | abort]* 


t 23 (4 :*none* 

debug points stop; 
There are some assertion points inside nginx that allow to stop nginx to attach the debugger, 
or to abort and to create the core file. 


应 该 适用 于 调试 ， 在 调试 器 内 设置 断 点 之 类 的 。 


error_log 
语法 :*error log file [ debug | info | notice | warn | error | crit ]* 
tà 23 (4 :*S(prefixy/logs/error.log* 


Nginx 添加 --with-debug 编译 参数 ， 你 还 能 够 使 用 以 下 配置 : 


error_log LOGFILE [ debug_core | debug_alloc | debug_mutex | debug_event 
]: | debug http | debug imap ; 


include 
语法 :*include file | ** 
ik (4 :*none* 


你 可 以 在 任意 地 方 使 用 include 指 令 实 现 配置 文件 的 包含 ， 类 似 于 apache 中 的 include 方 法 ， 可 
减少 主 配置 文件 d。 


include 指令 还 支持 像 下 面 配置 一 样 的 全 局 包含 的 方法 ， 例 如 包含 一 个 目录 下 所 有 
以 ".conf" 结 尾 的 文件 : 


include vhosts/*.conf; 


注意 路 径 受 到 configure 编 译 参 数 --prefix=< 路 径 > 指 今 的 影响 ， 如 果 没 有 指定 ，Nginx 默 认 是 被 
编译 在 /usr/local/nginx。 
i&ik:"lock file file* 


ik 4 4& :*compile-time option* 


lock file /var/log/lock_file; 


nginx uses accept mutex to serialize accept() syscalls. If nginx is built by gcc, Intel C++, or 
SunPro C++ compilers on i386, amd64, sparc64, and ppc64, then nginx uses the atomic 
instructions to implement the mutex. In other cases the lock file would be used. 


master_process 


i&ik:*master process on | off* 
t 23 (4 :*on* 
master process off; 
Do not use the "daemon" and "master process" directives in a production mode, these 
options are mainly used for development only. 


生产 环境 中 不 要 使 用 "daemon" 和 "master_process" 指 令 ， 这 些 选项 仅 用 于 开发 调试 。 
pid 
语法 :*pid file* 
缺 省 值 :*compile-time option* Example: 
pid /var/log/nginx.pid; 
进程 id 存储 文件 。 可 以 使 用 kill -HUP cat /var/log/nginx.pid\ 对 Nginx 进 行 配置 文 件 重 新 加 
载 。 
ssl engine 
i&ik:*ss| engine engine* 


tt £3 {A :*system dependent 


Here you can set your preferred openssl engine if any available. You can figure out which 
one do you have with the commandline tool: 


该 指令 用 于 指定 openssl 使 用 的 引 敬 。 你 可 以 通过 下 面 的 命令 行 获知 系统 目前 支持 的 openssl 引 
= 
openssl engine -t 


例如 : 


$ openssl engine -t 

(cryptodev) BSD cryptodev engine 

: [ available ] 

(dynamic) Dynamic engine loading support 
: [ unavailable ] 


timer resolution 
i&ik:*timer resolution t* 
tk {4 :*none* 


Example: 


timer resolution  100ms; 


The directive allows to decrease number gettimeofday() syscalls. By default gettimeofday() 
is called after each return from kevent(), epoll, /dev/poll, select(), poll(). 


But if you need an exact time in logs when logging $upstream response time, or $msec 


variables, then you should use timer resolution . 


user 

语法 :*user user [group]* 

tt {4 :*nobody nobody* 

指定 Nginx Worker 进 程 运 行 用 户 ， 默 认 是 nobody 帐 号 。 


例如 : 


user www users, 


worker_cpu_affinity 

语法 :*worker_cpu_affinity cpumask [cpumask...]* 

缺 省 值 :*none* 

Linux only. 

With this option you can bind the worker process to a CPU, it calls sched setaffinity(). 
仅 适 用 于 linux， 使 用 该 选项 可 以 绑 定 worker 进 程 和 CPU. 


For example， 


worker_proceses 4; 
worker_cpu_affinity 0001 0010 0100 1000; 


Bind each worker process to one CPU only. 


4j 3| 25 8 workerzt £2 Zg 3g — CPU. 


worker. proceses 27 
worker cpu affinity 0101 1010; 


Bind the first worker to CPUO/CPU2, bind the second worker to CPU 1/CPU3. This is suitable 
for HTT. 


将 CPUO/CPU2 线 定 给 第 一 个 worker 进 程 ， 将 CPU1/CPU3 绑 定 给 第 二 个 worker 进 程 。 


worker_priority 
i&ik:*worker priority [-] number* 
缺 省 值 :*on* 


With this option you can give to all worker processes the priority (nice) you need/wish, it calls 
setpriority(). 


使 用 该 选项 可 以 给 所 有 的 worker 进 程 分 配 优先 值 。 


worker_processes 
i&ik:*worker processes number* 
缺 省 值 :*1* 

e.g.: 


worker processes 5; 


nginx has the ability to use more than one worker process for several reasons: 
nginx 可 以 使 用 多 个 worker 进 程 ， 原 因 如 下 : 


1. to use SMP 
2. to decrease latency when workers blockend on disk I/O 
3. to limit number of connections per process when select()/poll() is used 


The worker_processes and worker_connections from the event sections allows you to 
calculate maxclients value: k 


max_clients = worker_processes * worker_connections 


worker_rlimit_core 
i&ik:*worker rlimit core size* 
缺 省 值 :' 


Maximum size of core file per worker; 


worker_rlimit_nofile 
语法 : worker_rlimit_nofile limit 缺 省 值 : " 
Specifies the value for maximum file descriptors that can be opened by this process. 


指定 


worker_rlimit_sigpending 

i&ik:*worker rlimit sigpending limit*#R f& : ' 

(Since Linux 2.6.8) Specifies the limit on the number of signals that may be queued for the 
real user ID of the calling process. 

working directory 

i&ik: working directory path tk (a: --prefix 


This is the working directory for the workers. It's used for core files only. nginx uses absolute 
paths only, all relative paths in configuration files are relative to --prefix--PATH 


Nginx 事 件 模块 


accept_mutex 


Syntax:*accept_mutex [ on | off ]* 
Default:*on* 


nginx 使 用 连接 互 斥 锁 进 行 顺 序 的 accept() 系 统 调 用 . 


accept mutex_delay 
Syntax:*accept_mutex_delay Nms;* 
Default:*500ms* 


如 果 一 个 进程 没有 互 斥 锁 ， 它 将 延迟 至 少 多 长 时 间 。 默 认 情况 下 ， 延 迟 是 500ms 。 


debug_connection 

Syntax:*debug_connection [ip | CIDR]* 

Default:*none* 

Since 0.3.54 this option support CIDR address format 

This option gives you the ability to write debug log only for the clients of this IP/NET. 
Several different directives are possible. 


Example: 


error_log /var/log/nginx/errors; 
events { 
debug_connection 192.168.1.1; 


devpoll changes 
devpoll events 
kqueue events 


epoll events 


Syntax:*devpoll_ changes* 
Default: 


These directives specify how many events may be passed to/from kernel, using appropriate 
method. 


The default devpoli values are 32, the rest are 512. 


multi accept 
Syntax:*multi accept [ on | off ]* 
Default:*off* 


multi accept tries to accept() as many connections as possible after nginx gets notification 
about a new connection. 


rtsig signo 
Syntax:*rtsig signo* 


Default: 


nginx uses two signals when the rtsig method is used. The directive specified the first 
signal number. The second is plus 1. 


By default rtsig signo is SIGRTMIN+10 (40). 
rtsig overflow events 
rtsig overflow test 


rtsig overflow threshold 


Syntax:*rtsigoverflow** 
Default: 


These directives specifies how to handle rtsig queue overflows. When overflow occurred 
nginx flushes rtsig queue, then it handles events switching between poll() and rtsig. poll() 
handles consecutively all unhandled events, while rtsig periodicaly drains queue to prevent a 
new overflow. When overflow is handled completely, nginx switches to rtsig method again. 


The rtsig_overflow_events specifies the number of events to be passed via poll(). The 
default is 16. 


The rtsig_overflow_test specifies after which number of events handled by poll() nginx will 
drains rtsig queue. The default is 32. 


The rtsig_overflow_threshold works in Linux 2.4.x only. Before to drain rtsig queue nginx 
looks in a kernel how the queue is filled up 


The default is 1/10. "rtsig overflow threshold 3" means 1/3. 


use 


Syntax:*use [ kqueue | rtsig | epoll | /dev/poll | select | poll | eventport ]* 
Default: 


如 果 在 ./configure 的 时 候 指定 了 不 止 一 种 事件 模型 ， 那 么 可 以 设置 其 中 一 个 ， 以 便 告诉 
nginx 使 用 哪 种 事件 模型 。 默 认 情 况 下 nginx 会 在 ./configure 时 找 出 最 适合 系统 的 事件 模型 。 


你 可 以 在 这 里 查看 可 用 的 事件 模型 以 及 如 何在 ./configure 时 激活 


worker_connections 


Syntax:*worker connections number* 
Default: 


通过 worker_connections 和 worker_proceses 可 以 计算 出 maxclients : 


max_clients = worker_processes * worker_connections 


作为 反 向 代理 ，max_clients 为 : 


max_clients = worker_processes * worker_connections/4 


Since a browser opens 2 connections by default to a server and nginx uses the fds (file 
descriptors) from the same pool to connect to the upstream backend 
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alias 


syntax:*alias file-path|directory-path;* 
default:*no* 
context:*location* 


This directive assigns a path to be used for the indicated location. Note that it may look 
similar to the root directive, but the document root doesn't change, just the file system path 
used for the request. 


For example: 


location /i/ ( 
alias / spool/w3/images/; 


} 


The request "/i/top.gif" will return the file "/spool/w3/images/top.gif". 
It is possible to use variables in the replacement path. 


The alias directive cannot be used inside a regex-specified location . If you need to do 
this you must use a combination of rewrite and root . 


client_body_in_file_only 
syntax:*client_body_in_file_only onloff* 

default:*off* 

context:*http, server, location* 

The directive enables to store a client request body in a file. 


Please note that the file at the request completion will not be removed if the directive is 
enabled. 


This directive can be used for debugging and for the $r->request_body_file method in the 
Embedded Perl module. 


client_body_in_single_buffer 
syntax:*client_body_in_single_buffer* 
default:*off* 

context:*http, server, location” 


The directive(0.7.58+) specifies whether to keep the whole body in a single client request 
buffer. The directive is recommended when using the variable $request_body to reduce the 
operations of copying. 


client_body_buffer_size 


syntax:*client_body_buffer_size the_size* 
default:*8k/16k* 

context:*http, server, location” 

The directive specifies the client request body buffer size. 


If the request body is more than the buffer, then the entire request body or some part is 
written in a temporary file. 


The default size is equal to two pages size, depending on platform it is either 8K or 16K. 


client_body_temp_path 
syntax:*client body temp path dir-path [ level1 [ level2 [ level3 ]* 
default:*client body temp* 

context:*http, server, location* 


The directive assigns the directory for storing the temporary files in it with the body of the 
request. 


In the dir-path a hierarchy of subdirectories up to three levels are possible. 


For example 


client body temp path /spool/nginx/client temp 1 2; 


The directory structure will be like this: 


/spool/nginx/client temp/7/45/00000123457 


client_body_timeout 


syntax:*client body timeout time” 

default:*60* 

context:*http, server, location* 

Directive sets the read timeout for the request body from client. 


The timeout is set only if a body is not get in one readstep. If after this time the client send 
nothing, nginx returns error "Request time out" (408). 


client header buffer size 


syntax:*client header buffer size size* 

default:*1k* 

context:*http, server* 

Directive sets the headerbuffer size for the request header from client. 

For the overwhelming majority of requests it is completely sufficient a buffer size of 1K. 


However if a big cookie is in the request-header or the request has come from a wap-client 
the header can not be placed in 1K, therefore, the request-header or a line of request- 
header is not located completely in this buffer nginx allocate a bigger buffer, the size of the 
bigger buffer can be set with the instruction large client header buffers. 


client header timeout 

syntax:*client header timeout time* 

default:*60* 

context:*http, server* 

Directive assigns timeout with reading of the title of the request of client. 

The timeout is set only if a header is not get in one readstep. If after this time the client send 


nothing, nginx returns error "Request time out" (408). 


client max body size 


syntax:*client max body size size* 


default:*client_max_body_size 1m* 
context:*http, server, location” 


Directive assigns the maximum accepted body size of client request, indicated by the line 
Content-Length in the header of request. 


If size is greater the given one, then the client gets the error "Request Entity Too Large" 
(413). 


It is necessary to keep in mind that the browsers do not know how to correctly show this 
error. 


default_type 


syntax:*default_type MIME-type* 
default:*default type text/plain* 
context:*http, server, location* 


Assigns the default MIME-type to be used for files where the standard MIME map doesn't 
specify anything. 


See also types 


Example: 


location = /proxy.pac { 
default_type application/x-ns-proxy-autoconfig; 
} 
location = /wpad.dat { 
rewrite . /proxy.pac; 
default_type application/x-ns-proxy-autoconfig; 


} 


directio 

syntax:*directio [size|off]* 
default:*directio off* 
context:*http, server, location* 


The directive enables use of flags O_DIRECT (FreeBSD, Linux), F_NOCACHE (Mac OS X) 
or directio() function (Solaris) for reading files with size greater than specified. This directive 
disables use of sendfile for this request. This directive may be useful for big files: 


directio 4m; 


error_page 


syntax:*error_page code [ code... ] [ = | =answer-code ] uri | @named_location* 
default:*no* 
context:*http, server, location, if in location* 


The directive specifies the URI, which will be showed for the errors indicated. 


Example: 
error_page 404 /404.html; 
error page 502 503 504  J/50x.html; 
error page 403 http://example.com/forbidden.html; 
error page 404 - Qfetch; 


Furthermore, it is possible to change the code of answer to another, for example: 


error page 404 -200 /.empty.gif; 


If an erroneous answer is processed by the proxied or FastCGI server and this server can 
return the different answer codes, for example, 200, 302, 401 or 404, then it is possible to 
hide the code returned: 


error page 404 = /404.php; 


If you wish to return the error code as-is, OMIT the = from the error_page directive: 


error_page 404 /404.php; 


if_ modified_since 

syntax:"if modified since [off|exact|before]* 
default:*if_modified_since exact* 
context:*http, server, location” 


The directive (0.7.24) defines how to compare time of file modification and time in request 
header "If-Modified-Since": 


e off — don't check "If-Modified-Since" request header (0.7.34); 

e exact — exact match; 

e before — file modification time should be less than time in "If-Modified-Since" request 
header. 


index 


syntax:*index file [file...]* 
default:*index index.html* 
context:*http, server, location* 


Directive determines the file(s) which will be used as the index. It's possible to use variables 
in the name of file. The presence of the files is checked in the order of their enumeration. A 
file with an absolute path can be put at the end. Example using a variable: 


index index.$geo.html index.O.html  /index.html; 


If you want to automatically generate an index from a directory listing, useautoindex on. 


internal 


syntax:*internal* 
default:*no* 
context:*location* 


internal indicates that the matching location can be used only for so called "internal" 
requests. 


For external requests it will return the error "Not found" (404). 
Internal requests are the following: 


e requests redirected by the instruction error page 

e subrequests created by the command include virtual of the "ngx http ssi module" 
module 

e requests changed by the instruction rewrite of the "ngx http rewrite module" module 


An example to prevent clients fetching error pages directly: 


error page 404 /404.htm1; 
location /404.html { 
internal; 


Nginx 0.7.x introduces a new syntax for internal locations: @location 


Example: 


location / { 
root /var/www/html; 
error page 404 Q40x; 


} 


location @40x { 
root /var/www/errors/40x.html; 


} 


keepalive_timeout 
syntax:*keepalive_timeout [ time ]* 
default:*keepalive_timeout 75* 
context:*http, server, location* 


The first parameter assigns the timeout for keep-alive connections with the client. The server 
will close connections after this time. 


The optional second parameter assigns the time value in the header 

Keep-Alive: timeout=time Ofthe response. This header can convince some browsers to 
close the connection, so that the server does not have to. Without this parameter, nginx 
does not senda Keep-Alive header (though this is not what makes a connection "keep- 
alive"). 


The parameters can differ from each other. 
Notes on how browsers handle the Keep-Alive header: 


e MSIE and Opera ignore the "Keep-Alive: timeout=" header. 

e MSIE keeps the connection alive for about 60-65 seconds, then sends a TCP RST. 
e Opera keeps the connection alive for a long time. 

e Mozilla keeps the connection alive for N plus about 1-10 seconds. 

e Konqueror keeps the connection alive for about N seconds. 


keepalive requests 


syntax:*keepalive_requests n* 
default:*keepalive_requests 100* 
context:*http, server, location” 


Number of requests which can be made over a keep-alive connection. 


large_client_header_buffers 
syntax:"large client header buffers number size* 
default:*large client header buffers 4 4k/8k* 
context:*http, server* 


Directive assigns the maximum number and size of buffers for large headers to read from 
client request. 


The request line can not be bigger than the size of one buffer, if the client send a bigger 
header nginx returns error "Request URI too large" (414). 


The longest header line of request also must be not more than the size of one buffer, 
otherwise the client get the error "Bad request" (400). 


Buffers are separated only as needed. 


By default the size of one buffer is equal to the size of page, depending on platform this 
either 4K or 8K, if at the end of working request connection converts to state keep-alive, then 
these buffers are freed. 


limit except 

syntax:*limit except methods {...}* 

default:*no* 

context:*location* 

Directive limits HTTP-methods, accessible inside location. 


For the limitation can be used the directives of modules ngx http access module and 
ngx http auth basic module: 


limit except GET { 
allow 192.168.1.0/32; 
deny all; 


limit_rate 

syntax:"limit rate speed* 

default:*no* 

context:*http, server, location, if in location* 


Directive assigns the speed of transmission of the answer to client. Speed is assigned in the 
bytes per second. Limitation works only for one connection, i.e., if client opens 2 
connections, then total velocity will be 2 times higher then the limit set. 


If itis necessary to limit speed for the part of the clients at the server level, based on some 
kind of condition - then this directive does not apply. Instead you should specify the limit by 
assigning the value to the $limit rate variable, as shown below: 


server { 
if ($slow) { 
set $limit_rate 4k; 
} 


limit_rate_after 


syntax:*limit rate after time* 
default:*limit rate after 1m* 
context:*http, server, location, if in location* 


The directive limits speed only after the first part was sent. 


limit rate after 1m; 
limit rate 100k; 


listen 


syntax:"listen address:port [ default [ backlog=num | rcvbuf=size | sndbuf=size | 
accept filter-filter | deferred | bind | ssl ] ]* 


default:*listen 80* 
context:*server* 


The listen directive specifies the address and port accepted by the enclosing server (...) 
block. It is possible to specify only an address, only a port, or a server name as the address. 


listen 127.0.0.1:8000; 


listen 127.0.0.1; 
listen 8000; 

listen *:8000; 

listen localhost:8000; 


IPv6 address(0.7.36) are set in square brackets: 


listen [::]:8000; 
listen [fe80::1]; 


When Linux (in contrast to FreeBSD) binds IPv6 [::], it will also bind the corresponding IPv4 
address. If other non IPv6 server definitions already used this, the bind will fail. By using 
explicit addresses instead of [::] this will not be a problem. It is also possible to specify that 
this listen directive is only to bind the IPv6 address with use of the "default ipv6only=on" 
option. Note that this only affect this listen directive, the same server {...} block may very well 
listen to IPv4 as well, specified by other listen directives. 


listen [2a02:750:5::123]:80; 
listen [::]:80 default ipv6only=on; 


If only address is given, the default port is 80. 


If the directive has the default parameter, then the enclosing server {...} block will be the 
default server for the address:port pair. This is useful for name-based virtual hosting where 
you wish to specify the default server block for hostnames that do not match any 

[£server name server name] directives. If there are no directives with the default 
parameter, then the default server will be the first server block in which the address:port 
pair appears. 


The listen directive accepts several parameters, specific to the system calls 1isten(2) 
and bind(2) . These parameters must follow the default parameter. 


backlog=num -- is assigned parameter backlog in call listen(2) . By default backlog equals 
-1. 


rcvbuf=size -- assigned to the parameter so ncvaur for the listening socket. 
sndbuf=size -- assigned to the parameter so swpBur for the listening socket. 
accept filter-filter -- is assigned name accept-filter. 


. It works only to FreeBSD, it is possible to use two filters -- dataready and httpready . On 
the signal -HUP accept-filter it is possible to change only in the quite last versions FreeBSD: 
6.0, 5.4-STABLE and 4.11-STABLE. deferred -- indicates to use that postponed accept(2) on 


Linux with 


. the aid of option TcP_DEFER_ACCEPT . bind -- indicates that it is necessary to make bind(2) 
separately 


. for this pair of address:port. The fact is that if are described several directives listen with 
the identical port, but by different addresses and one of the directives listen listens to on all 
addresses for this port (:port), then nginx will make bind(2) only to :port. It is necessary to 
consider that in this case for determining the address, on which the connections arrive, is 
done the system call getsockname(). But if are used parameters backlog, rcvbuf, sndbuf, 
accept_filter or deferred, then it is always done separately for this pair of address:port 
bind(2). ssl -- parameter (0.7.14) not related to listen(2) and bind(2) syscalls 


. but instead specifies that connections accepted on this port should work in SSL mode. This 
allows to specify compact configurations for servers working with both HTTP and HTTPS. 
For example: 


listen 80; 
listen 443 default ssl; 


Example of the use of the parameters: 


listen 127.0.0.1 default accept_filter=dataready backlog=1024; 


location 

syntax:*location [=|~|~|4~] /uri/ ( ... } 
default:*no* 

context:*server* 


This directive allows different configurations depending on the URI. It can be configured 
using both literal strings and regular expressions. To use regular expressions, you must use 
the a prefix: 


1. -* forcase insensitive matching 
2. - forcase sensitive matching 


To determine which /ocation directive matches a particular query, the literal strings are 
checked first. Literal strings match the beginning portion of the query and are case-sensitive 
- the most specific match will be used (see below on how nginx determines this). Afterwards, 


regular expressions are checked in the order defined in the configuration file. The first 
regular expression to match the query will stop the search. If no regular expression matches 
are found, the result from the literal string search is used. 


There are two ways to modify this behavior. The first is to use the prefix "=", which matches 
an exact query only. If the query matches, then searching stops and the request is handled 
immediately. For example, if the request "/" occurs frequently, then using "location = /" will 
expedite the processing of this request. 


The second is to use the prefix ^- . This prefix is used with a literal string and tells nginx to 
not check regular expressions if the path provided is a match. For instance, "location ^- 
/images/" would halt searching if the query begins with /images/ - all regular expression 
directives would not be checked. 


To summarize, the order in which directives are checked is as follows: 


1. Directives with the - prefix that match the query exactly. If found, searching stops. 

2. All remaining directives with conventional strings. If this match used the ^- prefix, 
searching stops. 

3. Regular expressions, in the order they are defined in the configuration file. 

4. If #3 yielded a match, that result is used. Otherwise, the match from #2 is used. 


It is important to know that nginx does the comparison against decoded URIs. For example, 
if you wish to match "/images/%20/test", then you must use "/images/ /test" to determine the 
location. 


Example: 


location = / { 


# matches the query / only. 
[ configuration A ] 
} 
location / { 
# matches any query, since all queries begin with /, but regular 
# expressions and any longer conventional blocks will be 


# matched first. 
[ configuration B ] 
y 
location ^- /images/ { 
# matches any query beginning with /images/ and halts searching, 
# so regular expressions will not be checked. 


[ configuration C ] 


location -* \.(gif|jpg|jpeg)$ { 
# matches any request ending in gif, jpg, or jpeg. However, all 
# requests to the /images/ directory will be handled by 


# Configuration C. 
[ configuration D ] 


} 


Example requests: 


e /-> configuration A 

e /documents/document.html -> configuration B 
e /images/1.gif -> configuration C 

e /documents/1.jpg -> configuration D 


Note that you could define these 4 configurations in any order and the results would remain 
the same. While nested locations are allowed by the configuration file parser, their use is 
discouraged and may produce unexpected results. 


How nginx Determines Which Path Matches 


Most users will not need to know how nginx internally determines which path to use - know 
that it will choose the "most specific" match for your URI in a speedy and efficient manner. 
For those that are curious, however, read on. 


All path strings are sorted alphabetically. nginx then proceeds to search down the list looking 
for matches until the request URI has a "higher" value then the current string in the sorted 
list. This is determined using the family of strcmp() functions - once strcmp() returns 1, 
then searching stops. Once searching stops, the last string which matched is used. 


For example, lets say we have the following paths: 


/ 

/a 
/apple 
/banana 


Now, lets say the server gets the path "/az". nginx would begin search down this list. First, "/" 
would match, but "/ is less than "/az" so searching continues. "/a" also matches, but "/a" is 
still less than "/az" so we continue again. "/apple" does not match. The next string, 
"/banana", is greater than "/az" so searching stops and the last match, "/a", would be used. 


Named Locations 


Later versions of Nginx (>0.7.x) have Named Locations. These are location blocks that start 
with an (à) symbol, and are treated similar to internal locations except that they preserve the 
original URI on internal redirects for error page or try files directives. 


location / { 
try files Qjoomla index.html; 


location Qjoomla { 
rewrite ^(.*)$ /index.php?q=$1 last; 


log_not_found 


syntax:*log_not_found [onloff]* 
default:*log_not_found on* 
context:*http, server, location” 


The directive enables or disables messages in error_log about files not found on disk. 


log_subrequest 


syntax:"log subrequest [on|off]* 
default:*log subrequest off* 
context:*http, server, location* 


The directive enables or disables messages in access_log about sub-requests such as 
rewrite rules and/or SSI requests. 


msie_padding 
syntax:*msie padding [on|off]* 
default:*msie padding on* 
context:*http, server, location* 


This directive enables or disables the the msie padding feature for MSIE browsers. When 
this is enabled, nginx will pad the size of the response body to a minimum of 512 bytes, for 
responses with a status code above or equal to 400. 


The padding prevents the activation of "friendly" HTTP error pages in MSIE, so as to not 
hide the more-informative error pages from the server. 


Note that Chromium/Chrome have "friendly" HTTP error pages as well, but this feature will 
not send them the padding. 


msie refresh 


syntax:*msie refresh [on|off]* 
default:*msie refresh off* 


context:*http, server, location* 


This directive allows or forbids issuing a refresh instead of doing a redirect for MSIE. 


open_file_cache 

syntax:*open file cache max = N [inactive = time] | off* 
default:*open_file_cache off* 

context:*http, server, location” 

The directive sets the cache activity on. These information can be stored: 


e Open file descriptors, information with their size and modification time; 

e Information about the existence of directories; 

e Error information when searches for a file - no file, do not have rights to read, etc. See 
also open file cache errors 


Options directive: 


* max - specifies the maximum number of entries in the cache. When the cache 
overflows, the longest-used items(LRU) will be removed; 

e inactive - specifies the time when the cached item is removed, if it has not been 
downloaded during that time, the default is 60 seconds; 

e off - prohibits the cache activity. 


Example: 


open file cache max-1000 inactive-20s; 
open file cache valid 30s; 

open file cache min uses 2; 

open file cache errors on; 





open file cache errors 
syntax:*open file cache errors on | off* 
default:*open file cache errors off* 
context:*http, server, location* 


The directive specifies to cache errors or not when searching a file. 


open_file_cache_min_uses 
syntax:*open file cache min uses number* 


default:*open file cache min uses 1* 


context:*http, server, location” 


The directive defines the minimum use number of a file within the time specified in the 
directive parameter inactive in open_file_cache. ?If use more than the number, the file 
descriptor will remain open in the cache. 


open_file_cache_valid 
syntax:*open file cache valid time* 
default:*open file cache valid 60* 
context:*http, server, location* 


The directive specifies the time when need to check the validity of the information about the 
item in open_file_cache. 


optimize_server_names 
syntax:*optimize_server_names [ onloff ]* 
default:*optimize_server_names on* 
context:*http, server* 


Directive activates or deactivates optimization of host name checks for name-based virtual 
servers. 


In particular, the check influences the name of the host used in redirects. If optimization is 
on, and all name-based servers listening on one address:port pair have identical 
configuration, then names are not checked during request execution and redirects use first 
server name. 


If redirect must use host name passed by the client, then the optimization must be turned off. 


Note: this directive is deprecated in nginx 0.7.x, use server_name_in_redirect instead. 


port_in_redirect 
syntax:*port_in_redirect [ on|off ]* 
default:*port_in_redirect on* 
context:*http, server, location” 


Directive allows or prevents port indication in redirects handled by nginx. 


If port_in_redirect is on, then Nginx will not add the port in the url when the request is 
redirected. 


recursive_error_pages 


syntax:*recursive_error_pages [on|off]* 
default:*recursive_error_pages off* 
context:*http, server, location” 


recursive error pages enables or disables following a chain of error page directives. 


resolver 


syntax:*resolver address* 
default:*no* 
context:*http, server, location* 


TODO: Description 


resolver timeout 


syntax:*resolver timeout time* 
default:*30* 
context:*http, server, location* 


Resolver timeout in seconds. 


root 


syntax:*root path* 
default:*root html* 
context:*http, server, location, if in location* 


root specifies the document root for the requests. For example, with this configuration 


location /i/ { 
root /spool/w3; 


} 


A request for "/i/top.gif" will return the file "/spool/w3/i/top.gif". You can use variables in the 
argument. 


note: Keep in mind that the root will still append the directory to the request so that a 
request for "/i/top.gif" will not look in "/spool/w3/top.gif" like might happen in an Apache-like 
alias configuration where the location match itself is dropped. Use the alias directive to 
achieve the Apache-like functionality. 


satisfy any 
syntax:*satisfy any [ onloff ]* 
default:*satisfy any off* 
context:*location* 


Directive solves access with at least one successful checking, executed by modules 
NginxHttpAccessModule orNginxHttpAuthBasicModule: 


location / { 
satisfy any on; 
allow 192.168.1.0/32; 


deny all; 
auth basic "closed site"; 
auth basic user file conf/htpasswd; 


send timeout 


syntax:*send timeout the time* 
default:*send timeout 60* 
context:*http, server, location* 


Directive assigns response timeout to client. Timeout is established not on entire transfer of 
answer, but only between two operations of reading, if after this time client will take nothing, 
then nginx is shutting down the connection. 


sendfile 


syntax:*sendfile [ on|off ]* 
default:*sendfile off* 


context:*http, server, location* 


Directive activate or deactivate the usage of sendfile() . 


server 


syntax:*server (...)* 


default:*no* 


context:*http* 


Directive assigns configuration for the virtual server. 


There is no separation of IP and name-based (the Host header of the request) servers. 


Instead, the directive listen is used to describe all addresses and ports on which incoming 


connections can occur, and in directive server name indicate all names of the server. 


server name 


syntax:*server name name [... ]* 


default:*server name hostname* 


context:*server* 


This directive performs two actions: 


Compares the Host header of the incoming HTTP request against the server ( ... ) 
blocks in the Nginx configuration files and selects the first one that matches. This is how 
virtual servers are defined. Server names are processed in the following order: 


full, static names 


names with a wildcard at the start of the name — *.example.com 
names with a wildcard at the end of the name — www.example.* 
names with regular expressions 


If there is no match, a [#server server ( ... )] block in the configuration file will be used based 


on the following order: 


1. 
2: 


3. 


the server block with a matching listen directive marked as default 
the first server block with a matching listen directive (or implicit listen 80; ) 


Sets the server name that will be used in HTTP redirects if server name in redirect is 
set. 


Example: 


server { 


server_name example.com www.example.com; 


} 


The first name becomes the basic name of server. By default the name of the machine 
(hostname) is used. 


It is possible to use "*" for replacing the first or the last part of the name: 


server { 
server_name example.com *.example.com www.example.*; 


} 


Two of the above given names can be combined into one: 


server { 
server_name .example.com; 


} 


It is also possible to use regular expressions in server names, prepending the name with a 
tilde "~" like so: 


server { 
server name www.example.com ~^www\d+\.example\.com$; 


The basic name of server is used in an HTTP redirects, if no Host header was in client 
request or that header does not match any assigned servername. You can also use just "" to 
force Nginx to use the Host header in the HTTP redirect (note that "" cannot be used as the 
first name, but you can use a dummy name such as ™ instead): 


server { 
server name example.com *; 


} 


server { 
server_name _ *; 


} 


Note that this has changed in 0.6.x and is now: 


server { 
server name  ; 


Since nginx 0.7.12, an empty server name is supported, to catch the requests without "Host" 
header: 


server { 
server name ""; 


} 


server_name_in_redirect 


syntax:*server_name_in_redirect on|off* 
default:*server_name_in_redirect on* 
context:*http, server, location” 


If server name in redirect is on, then Nginx will use the first value of the server name 
directive for redirects. If server name in redirect is off, then nginx will use the requested 
Host header. 


server names hash max size 


syntax:*server names hash max size number* 
default:*server names hash max size 512* 
context:*http* 


The maximum size of the server name hash tables. For more detail see the description of 
tuning the hash tables in Nginx Optimizations. 


server names hash bucket size 


syntax:*server names hash bucket size number* 
default:*server names hash bucket size 32/64/128* 
context:*http* 


Directive assigns the size of basket in the hash-tables of the names of servers. This value by 
default depends on the size of the line of processor cache. For more detail see the 
description of tuning the hash tables in Nginx Optimizations. 


server tokens 


syntax:*server tokens on|off* 


default:*server_tokens on* 
context:*http, server, location” 


Whether to send the Nginx version number in error pages and server header. 


tcp_nodelay 


syntax:*tcp_nodelay [on|off]* 
default:*tcp_nodelay on* 
context:*http, server, location” 


This directive allows or forbids the use of the socket option TcP_NoDELAY . Only included in 
keep-alive connections. 


You can read more about the TcP_NoDELAY socket option here. 


tcp_nopush 
syntax:*tcp_nopush [on|off]* 
default:*tcp_nopush off* 
context:*http, server, location” 


This directive permits or forbids the use of the socket options TcP_NoPUSH on FreeBSD or 
TCP_CORK on Linux. This option is only available when using sendfile . 


Setting this option causes nginx to attempt to send it's HTTP response headers in one 
packet on Linux and FreeBSD 4.xReadMoreAboutTcpNopush 


try_files 

syntax:*try files file1 [file2 ... filen] fallback* 
default:*none* 

context:*location* 


This directive tells Nginx to test for each file's existence, and use the first found file as the 
URI. If none of the files are found, then the location fallback is called ("fallback" can be 
any name). fallback is a required parameter. It can be a named location or any 
guaranteed URI. 


Example: 


location / { 


try_files index.html index.htm @fallback; 
} 


location @fallback { 


root /var/www/error; 
index index.html; 


} 


types 


syntax:*types (...)* 
context:*http, server, location* 


Directive assigns the correspondence of expansion and MIME-types of answers. To one 
MIME- type can correspond several expansions. By default it is used these 
correspondences: 


types { 
text/html html; 
image/gif gif; 


image/jpeg jpg; 
} 


The sufficiently complete table of mappings is included and is located in the file 


conf/mime.types . 


So that for that determined location's for all answers would reveal MIME- type 
application/octet-stream , it is possible to use the following: 


location /download/ { 


types t 
default type application/octet-stream; 
} 

水野 

变星 


The core module supports built-in variables, whose names correspond with the names of 
variables in Apache. 


First of all, there are the variables, which represent the lines of the title of the client request, 
forexample, $http_user_agent , $http_cookie , and so forth. 


Furthermore, there are other variables: 


$arg PARAMETER 


This variable contains the value of the cet request variable PARAMETER if present in the 


query string 


$args 


This variable is equal to arguments in the line of request; 


$binary_remote_addr 


The address of the client in binary form; 


$body_bytes_sent 


(undocumented) 


$content_length 


This variable is equal to line Content-Length in the header of request; 


$content_type 


This variable is equal to line Content-Type in the header of request; 


$cookie_ COOKIE 


The value of the cookie COOKIE; 


$document_root 


This variable is equal to the value of directive root for the current request; 


$document_uri 


The same as $uri. 


$host 


This variable is equal to line Host in the header of request or name of the server 


processing the request if the Host header is not available. 


$http HEADER 


The value of the HTTP header HEADER when converted to lowercase and with 'dashes' 


converted to 'underscores', e.g. $http user agent, $http_referer...; 
$is args 

Evaluates to "?" if $args is set, "" otherwise. 

$limit rate 

This variable allows limiting the connection rate. 


$query string 


The same as $args. 


$remote addr 


The address of the client. 


$remote port 


The port of the client; 


$remote user 


This variable is equal to the name of user, authenticated by the Auth Basic Module; 


$request filename 


This variable is equal to path to the file for the current request, formed from directives root or 
alias and URI request; 


$request body 


This variable(0.7.58+) contains the body of the request. The significance of this variable 
appears in locations with directives proxy pass or fastcgi pass. 


$request body file 


Client request body temporary filename; 


$request_completion 


(undocumented) 


$request_method 


This variable is equal to the method of request, usually GET or PoST . 


$request_uri 


This variable is equal to the complete initial URI together with the arguments; 


$scheme 
The HTTP scheme (i.e. http, https). Evaluated only on demand, for example: 


rewrite A(.+)$ $scheme://example.com$1 redirect; 


$server_addr 


Equal to the server address. As a rule, for obtaining the value of this variable is done one 
system call. In order to avoid system call, it is necessary to indicate addresses in directives 
listen and to use parameter bind . 


$server_name 


The name of the server. 


$server_port 


This variable is equal to the port of the server, to which the request arrived; 


$server_protocol 


This variable is equal to the protocol of request, usually this HTTP/1.0 Or HTTP/1.1 . 


$uri 


This variable is equal to current URI in the request, it can differ from initial, for example by 
internal redirects, or with the use of index it is file with internal redirects. 
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Httplndex 模 块 
这 个 模块 提供 一 个 简单 方法 来 实现 在 轮 询 和 客户 端 IPP 之 间 的 后 端 服务 器 负荷 平衡 。 


配置 范例 : 


upstream backend { 
server backend1.example.com weight=5; 
server backend2.example.com: 8080; 
server unix:/tmp/backend3; 


} 


server { 
location / { 
proxy_pass http://backend; 


ip_hash 


syntax: ip_hash 
default: none 
context: upstream 


This directive causes requests to be distributed between upstreams based on the IP- 
address of the client. The key for the hash is the class-C network address of the client. This 
method guarantees that the client request will always be transferred to the same server. But 
if this server is considered inoperative, then the request of this client will be transferred to 
another server. This gives a high probability clients will always connect to the same server. 


范例 : 


upstream backend { 
ip_hash; 
server backend1.example.com; 
server backend2.example.com; 
server backend3.example.com down; 
server backend4.example.com; 


server 


syntax: server name [parameters] 


default: none 


context: upstream 


HttpAccess 模 块 
此 模块 提供 了 一 个 简易 的 基于 主机 的 访问 控制 . 


ngx http access module 模块 使 有 可 能 对 特定 IP 客 户 端 进行 控制 . 规则 检查 按照 第 一 次 匹配 
的 顺序 


配置 样 例 


location / { 

: deny 192.168.1.1; 

: allow 192.168.1.0/24; 
: allow 10.1.1.0/16; 

: deny all; 


在 上 面 的 例子 中 , 仅 人 允许 网 段 10.1.1.0/16 和 192.168.1.0/24 BRR 192.168.1.1 之 外 的 ip 访问 . 


当 执 行 很 多 规则 时 ,最 好 使 用 ngx_http_geo_module 模块 . 


指导 


e [# 放 行 放行 ] 
。 HRI 禁止 ] 


syntax:*allow [ address | CIDR | all ]* 
default:*no* 
context:*http, server, location, limit_except* 


以 上 描述 的 网 络 地 址 有 权 直 接 访问 


禁止 

syntax:*deny [ address | CIDR | all ]* 
default:*no* 

context:*http, server, location, limit except* 


以 上 描述 的 网 络 地 址 拒绝 访问 
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HttpAccess 模 块 
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HttpAuthBasic 模 块 


该 模块 可 以 使 你 使 用 用 户 名 和 密码 基于 HTTP. 基本 认证 方法 来 保护 你 的 站 点 或 其 部 分 内 容 。 


实例 配置 

location / { 

: auth_basic "Restricted"; 
: auth_basic_user_file conf/htpasswd; 
H 

BA 

AT 


e [#auth_basic auth_basic] 
e [#auth_basic_user_file auth basic user file] 


auth basic 

语法 : *auth basic [ textloff ]* 

默认 值 : *auth basic off* 

作用 域 : *http, server, location, limit except* 

该 指令 包含 用 于 HTTP 基本 认证 的 测试 名 和 密码 。 分 配 的 参数 用 于 认证 领域 。 值 "off" 可 以 使 
其 覆盖 来 自 上 层 指 使 的 继承 性 。 


auth basic user file 

i&ik : *auth basic user file the file* 
默认 值 : *no* 

作用 域 : *http, server, location, limit except* 
该 指 今 为 某 认 证 领域 指定 htpasswd 文件 名 。 
文件 格式 类 似 于 下 面 的 内 容 : 


用 户 名 :密码 
用 户 名 2 :密码 2 :注释 
用 户 名 3 :密码 3 


密码 必须 使 用 画 数 crypt(3) 加 密 。 你 可 以 使 用 来 自 Apache 的 htpasswd 工具 来 创建 密码 文 
件 。 


你 也 可 以 使 用 perl 创建 密码 文件 ,pw.pl MAR : 
#!/usr/bin/perl 
use strict; 


my $pw=$ARGV[O] ; 
print crypt ($pw, $pw)."\n"; 


然后 执行 


chmod +x pw.pl 
./pw.pl password 
papAq5PwY/QQM 


papAq5PwY/QQM 就 是 password 的 crypt() 密 码 


参考 


原始 文档 


HttpAutoindex 模 块 


此 模块 用 于 自动 生成 目录 列表 . 
ngx_http_autoindex_module 只 在 ngx_http_index_module 模 块 未 找到 索引 文件 时 发 出 请 求 . 


配置 实例 


location / { 
: autoindex on; 


} 


指导 


e [#autoindex autoindex] 
e [#autoindex_exact_size autoindex_exact_size] 
e [#autoindex_localtime autoindex_localtime] 


autoindex 


syntax:*autoindex [ onloff ]* 
default:*autoindex off* 
context:*http, server, location” 


激活 /关闭 自动 索引 


autoindex_exact_size 


syntax:*autoindex_exact_size [ on|off ]* 
default:*autoindex_exact_size on* 
context:*http, server, location” 


设 定 索 引 时 文件 大 小 的 单位 (B,KB, MB 或 GB) 


autoindex_localtime 


syntax:*autoindex_localtime [ on|off ]* 
default:*autoindex localtime off* 


context:*http, server, location* 


开启 以 本 地 时 间 来 显示 文件 时 间 的 功能 。 默 认为 关 (GMT AY H) 


参考 


Original Documentation 


Browser 模 块 


摘要 


This module creates variables, the values of which depend on the request header "User- 
agent": 


本 模块 的 变量 基于 请 求 头 (header) 中 的 "User-agent" 


e $modern_browser - is equal to the value, assigned by directive modern browser value, 


if browser is identified as an modern browser; 


e $ancient browser - 当 等 于 指定 给 modern_browser value 的 浏览 器 时 ， 这 个 浏览 器 被 认 


定 为 新 版 的 浏览 器 ; 


e $ancient_browser - is equal to the value, assigned by directive ancient_browser_value, 


if browser is identified as an old browser; 
e $ancient_browser - 当 等 于 指定 给 ancient_browser_ value 的 浏览 器 时 ， 这 个 浏览 器 被 认 
定 为 老 版 的 浏览 器 ; 
e $msie - is equal 1, if browser is identified as MSIE with any version; 
e $msie - 当 浏 览 器 为 MSIE 的 任何 版 本 时 ， 这 个 值 等 于 1; 


If you don't need this module add --without-http_browser_module parameter to the 
./configure call, at compile time. 


如 果 不 需 要 这 个 模块 时 ， 在 编译 的 时 候 加 上 --without-http_browser_module. 
Example configuration 例如 配置 
Selection of the index file: 


选择 索引 文件 : 


modern_browser_value "modern."; 
modern_browser msie 5.5; 
modern_browser gecko 1.0.0; 
modern_browser opera 9.0; 
modern_browser safari 413; 


modern_browser konqueror 3.0; 
index index.${modern_browser}html index.html; 


Redirect for the old browsers: 


定义 老 的 浏览 器 : 


modern_browser msie 5.0; 


modern_browser gecko 0.9.1; 
modern_browser opera 8.0; 
modern_browser safari 413; 
modern_browser konqueror 3.0; 


modern_browser unlisted; 
ancient_browser Links Lynx Netscape4; 


if ($ancient_browser) { 
rewrite ^  /ancient.html; 


ancient browser 


syntax:*ancient browser line [ line... ]* 
default:*no* 
context:*http, server, location* 


Directive assigns the substrings, during presence of which in the line "User-agent", browser 
are considered as old. 
Special line "netscape4" corresponds to regular expression "^Mozilla/[1-4] ". 


ancient browser value 


syntax:*ancient browser value line* 
default:*ancient browser value 1* 

context:*http, server, location* 

Directive assigns value for the variables $ancient_browser. 


定义 $ancient_browser 的 变量 值 . 


modern_browser 


syntax:*modern_browser browser version|unlisted* 
default:*no* 


context:*http, server, location” 


Directive assigns which version of the browser is to be considered as modern. 
As browser you can assign the values msie, gecko (Mozilla-based browsers) opera, safari, 
konqueror. 


Of versions it is possible to assign in size X, X.X, X.X.X, or X.X.X.X. maximum values for 
each of their sizes respectively - 4000, 4000.99, 4000.99.99, and 4000.99.99.99. 


Special value "unlisted" indicates to consider modern browser, not described by the 
modern_browser and ancient_browser directives. 

Otherwise the neperechislennyy browser will be considered become obsolete. 

If the headers do not contain "User-agent", the browser is considered neperechislennym. 


modern_browser_value 
syntax:*modern browser value line* 
default:*modern browser value 1* 

context:*http, server, location* 

Directive assigns value for the variables $modern browser. 


XE 3| $modern browserf ¥ 4. 
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Charset45" $ 


This module adds the text encoding to the "Content-Type indicated" response-header. 


Furthermore, module can reencode data of one encoding into another. It is necessary to 
note that the reencoding is accomplished only in one direction - from the server to the client, 
and only one-byte encodings can be reencoded. 


Example configuration: 


charset windows-1251; 
source charset  koi8-r; 


$ IN 4P 


charset 


syntax:*charset encoding|off* 
default:*charset off* 
context:*http, server, location, if in location* 


The directive charset adds the line "Content-Type" into response-header with indicated 
encoding. If this encoding is differed from that indicated in directive source_charset, then 
reencoding is carried out. The parameter "off" deactivate the insertation of the line "Content- 
Type" in the response-header. 


charset_map 


syntax:*charset_map encoding1 encoding2 {...}* 
default:*no* 
context:*http, server, location” 


The directive charset_map describes the table of reencoding from one encoding into 
another. A table for the inverse reencoding is created using the same data. The codes of 
symbols are assigned in hexadecimal form. If no recorded symbols are in the range 80-FF 
they will be substituted with '?'. 


Example usage: 


charset_map koi8-r windows-1251 { 
CO FE ; # small yu 
C1 EO ; # small a 


C2 E1 ; # small b 
C3 F6 ; # small ts 
no 


} 


The complete table of conversion from koi8-r into Windows-1251 is distributed with nginx 
and is located in file conf/koi-win. 


override_charset 


syntax:*override_charset on|off* 
default:*override_charset off* 
context:*http, server, location, if in location* 


This directive determines, to carry out reencoding for the response, obtained from the 
proxied server or from FastCGl-server, if in the response-header a "Content-Type" header 
already is. If reencoding is permitted, then as the initial encoding the encoding, indicated in 
the obtained answer, is used. 


It is necessary to note that if the response was obtained in the subquery then, independent 
of directive override_charset, is always carried out reencoding from encoding of the 
response into encoding of basic demand. 


source_charset 

syntax:*source_charset encoding* 

default:*no* 

context:*http, server, location, if in location* 

The directive source_charset assigns the initial encoding of response. If this encoding is 
differed from that indicated in directive charset, then reencoding is carried out. 


References 
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HttpEmptyGif 模 块 
本 模块 在 内 存 中 常 驻 了 一 个 1x1 的 透明 GIF 图 像 ， 可 以 被 非常 快速 的 调用 。 


示例 : 


location = /_.gif { 

: empty_gif; 

H 
EZ. 

AT 

e [#empty_gif empty_gif] 


empty gif > 
语法 : *empty_gif* 
默认 值 : *n/a* 


fF FHis*location* 


参见 


z 


原始 文档 


HttpFcgi 模 块 
这 个 模块 允许 Nginx 与 FastCGI 进程 交互 ， 并 通过 传递 参数 来 控制 FastCGI 进程 工作 。 


配置 实例 : 


location / { 
fastcgi_pass localhost :9000; 
fastcgi_index index.php; 


fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name; 


fastcgi_param QUERY_STRING $query_string; 
fastcgi param REQUEST_METHOD $request_method; 
fastcgi_param CONTENT_TYPE $content_type; 
fastcgi_param CONTENT_LENGTH $content_length; 
} 
语法 


fastcgi_buffers 


syntax: fastcgi_buffers the_number is_size; 

default: fastcgi_buffers 8 4k/8k; 

context: http, server, location 

该 指令 集 设置 缓冲 区 的 数量 和 大 小 ， 用 于 缓存 从 FastCGI Server 接收 到 的 数据 。 默 认 情 况 下 ， 一 个 缓冲 区 的 大 小 相关 
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fastcgi_buffer_size 


syntax: fastcgi_buffer_size the_size 
default: fastcgi_buffer_size 4k/8k 
context: http, server, location 


This directive sets the buffersize, into which will be read the first part of the response, 
obtained from the fastcgi server. 


In this part of response the small response-header is located, as a rule. 
By default, the buffersize is equal to the size of one buffer in directive fastcgi_buffers; 


however, it is possible to set it to less. 


fastcgi_cache 


syntax: fastcgi_cache zone; 


default: none 
context: http, server, location 


设置 缓存 在 共享 内 存 中 的 名 称 . 一 块 区 域 可 以 被 用 于 不 用 的 地 方 . 


fastcgi_cache_key 
syntax: fastcgi_cache_key line ; 
default: none 

context: http, server, location 


设置 缓存 的 key, 例 : 


fastcgi_cache_key localhost: 9000 $ request_uri; 


fastcgi_cache_methods 

syntax: fastcgi_cache_methods [GET HEAD POST]; 
default: fastcgi_cache_methods GET HEAD; 
context: main,http,location 


GET/HEAD is syntax sugar, i.e. you can not disable GET/HEAD even if you set just 


fastcgi_cache_methods POST; 


fastcgi_cache_min_uses 


syntax: fastcgi_cache_min_uses n 
default: fastcgi_cache_min_uses 1 
context: http, server, location 


TODO: Description. 


fastcgi_cache_path 


syntax: fastcgi cache path /path/to/cache [levels=m:n keys zone-name:time inactive=time 
clean time-time] 


default: none 


context: http, server, location 


TODO: Description. 


fastcgi cache use stale 


syntax: fastcgi cache use stale [updating|error|timeout|invalid header|http 500] 
default: fastcgi cache use stale off; 
context: http, server, location 


TODO: Description. 


fastcgi cache valid 


syntax: fastcgi cache valid [http error code|time] 
default: none 
context: http, server, location 


TODO: Description. 


fastcgi index 


syntax: fastcgi index file 
default: none 
context: http, server, location 


The name of the file which will be appended to the URI and stored in the variable $fastcg 


[L| eeu 





fastcgi hide header 


syntax: fastcgi hide header name 


context: http, server, location 





默认 情况 下 Nginx 不 会 从 FastCGI 进程 里 给 客户 端 发 送 "Status" WI"X-Accel-..." 消息 头 。 这 个 指令 可 以 用 来 掩 
如 果 需 要 "Status" 和 "X-Accel-..." 消息 头 ， 那 就 需要 使 用 这 个 指令 让 FastCGI 强制 发 送 消息 头 给 客户 端 。 





EE 


fastcgi_ignore_client_abort 


syntax: fastcgi_ignore_client_abort on|off 





default: fastcgi_ignore_client_abort off 





context: http, server, location 


这 个 指令 用 来 决定 忽略 用 户 取消 的 请 求 。 


fastcgi_intercept_errors 


syntax: fastcgi_intercept_errors on|off 

default: fastcgi_intercept_errors off 

context: http, server, location 

这 个 指令 用 来 决定 是 否 要 把 客户 端 转 向 4Xx 和 5Xxx 错 误 页 ， 或 允许 Nginx 自 动 指定 错误 页 页 。 
注意 : 你 需要 在 此 明确 错误 页 , 它 才 是 有 用 的 。Igor 便 说 : “如果 没 有 定制 的 处 理 机 制 ，Nginx 不 会 拦截 一 个 没有 缺 省 页 
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fastcgi_param 


syntax: fastcgi_param parameter value 

default: none 

context: http, server, location 

该 指令 指定 的 参数 , 将 被 传递 给 FastCGI-Sserver。 

它 可 能 使 用 字符 串 、 变 量 及 其 它们 的 组 合 来 作为 参数 值 。 如 果 不 在 此 制定 参数 ， 它 就 会 继承 外 层 设 置 ; 如 果 在 此 设置 了 
下 面 是 一 个 例子 , 对 于 PHP 来 说 的 最 精简 的 必要 参数 : 


fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name; 
fastcgi_param QUERY_STRING $query_string; 


参数 SCRIPT_FILENAME 是 PHP 用 来 确定 执行 脚本 的 名 字 ， 而 参数 QUERY_STRING 是 它 的 一 个 子 参数 。 
如 果 要 处 理 POST, 那么 这 三 个 附加 参数 是 必要 的 : 
fastcgi param REQUEST_METHOD $request_method; 


fastcgi_param CONTENT_TYPE $content_type; 
fastcgi param CONTENT LENGTH $content length; 


如 果 PHP 在 编译 时 使 用 了 - -enable-force-cgi-redirect 选 项 ， 设 置 参 数 REDIRECT_STATUS 的 值 为 200 就 是 必须 E 


fastcgi param REDIRECT_STATUS 200; 


EEE] 





Geo 模 块 


摘要 


This module creates variables, whose values depend on the IP-address of the client. 


Example configuration: 


geo $geo { 


default 
127.0.0.1/32 
192.168.1.0/24 
10.1.0.0/16 


-- 


- 


PENO 


~ 


geo 

syntax:*geo [$ip_variable] $variable ( ... }* 
default: none 

context:*http* 


The directive describes the dependency of the value of a variable on the IP-address of a 
client. By default, the IP-address used for the lookup is $remote addr, but since version 
0.7.27 itis possible to specify which variable should be used. 


geo $arg remote addr $geo { 


j 


n 


Addresses are assigned in the form CIDR. Furthermore, there are four special parameters: 
Example of the description: 


e delete — deletes the specified network (0.7.23). 

e default - the value of variable, if the client address does not correspond to any assigned 
address. It is possible so to write instead of default 0.0.0.0/0. 

e include - text file with addresses and values information. Several files can be inluded 
like this. 

e proxy - specifies the address of proxy server (0.8.7). NEED MORE DESCRIPTION... 

e ranges — specifies that the addresses specified are in the form of ranges (0.7.23). This 


directive must be the first. 


geo $country { 


default no; 
include conf/geo.conf; 
127.0.0.0/24 us; 
127.0.0.1/32 ru; 
10.1.0.0/16 ru; 


192.168.1.0/24 uk; 


In the file conf/geo.conf: 


10.2.0.0/16 ru; 
192.168.2.0/24 ru; 


The value will be the the one with maximum agreement. For example, the IP address 
127.0.0.1 will get the value "ru", but not "us". 


Example with ranges: 


geo $country { 


ranges; 
default no; 
127.0.0.0-127.0.0.0 us; 
127.0.0.1-127.0.0.1 ru; 
127.0.0.1-127.0.0.255 us; 
10.1.0.0-10.1.255.255 ru; 
192.168.1.0-192.168.1.255 uk; 
} 
References 
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e Original Documentation 


HttpGzip 模 块 


这 个 模块 支持 在 线 实时 压缩 输出 数据 流 


使 用 范例 
: gzip on; 
: gzip min length 1000; 
: gzip proxied expired no-cache no-store private auth; 
: gzip types text/plain application/xml; 


Aes Æ $gzip ratio 可 以 获取 到 gzip 的 压缩 比率 
BA 
AT 


e [#gzip gzip] 

e [#gzip_buffers gzip buffers] 

e [fgzip comp level gzip comp level] 
e [£gzip min length gzip min length] 

e [f&gzip http version gzip http version] 
e [#gzip_proxied gzip proxied] 

e [#gzip_types gzip types] 


gzip 

语法 :*gzip on|off* 

默认 值 :*gzip off* 

作用 域 :*http, server, location, if (x) location* 


开启 或 者 关闭 gzip 模 块 


gzip_buffers 


语法 :*gzip_buffers number size* 
默认 值 :*gzip_buffers 4 4k/8k* 
作用 域 :*http, server, location* 


设置 系统 获取 几 个 单位 的 缓存 用 于 存储 gzip 的 压缩 结果 数据 流 。 例如 4 AK 代表 以 4k 为 单位 ， 
按照 原始 数据 大 小 以 4k 为 单位 的 4 倍 申请 内 存 。 4 8k 代表 以 8k 为 单位 ， 按 照 原始 数据 大 小 以 
8k 为 单位 的 4 倍 申请 内 存 。 


如 果 没 有 设置 ， 默 认 值 是 申请 跟 原 始 数据 相同 大 小 的 内 存 空间 去 存储 gzip 压 缩 结 果 。 


gzip_comp_level 


i&ik:*gzip comp level 1..9* 

E &:*gzip comp level 1* 

作用 域 :*http, server, location* 

gzip 压 缩 比 ，1 压缩 比 最 小 义理 速度 最 快 ，9 压缩 比 最 大 但 义理 最 慢 (传输 快 但 比较 消耗 
cpu) 。 

gzip_min_length 

语法 :*gzip_min_length length* 

默认 值 :*gzip_min_length 0* 

作用 域 :*http, server, location* 

设置 允许 压缩 的 页 面 最 小 字 节 数 ， 页 面 字 节 数 从 header 头 中 的 Content-Length 中 进行 获取 。 
默认 值 是 0， 不 管 页 面 多 大 都 压缩 。 


建议 设置 成 大 于 1k 的 字 节 数 ， 小 于 1k 可 能 会 越 压 越 大 。 即 : gzip_min_length 1024 


gzip_http_version 
语法 :*gzip_http_version 1.0|1.1* 
默认 值 :*gzip_http_version 1.1* 
作用 域 :*http, server, location* 


别 http 的 协议 版 本 。 由 于 早期 的 一 些 浏 览 器 或 者 http 客 户 端 ， 可 能 不 支持 gzip 自 解压 ， 用 户 
就 会 看 到 乱码 ， 所 以 做 一 些 判 断 还 是 有 必要 的 。 注 : 21 世 纪 都 来 了 ， 现 在 除了 类 似 于 百度 的 
蛟 蛛 之 类 的 东西 不 支持 自 解压 ，99.99% 的 浏览 器 基本 上 都 支持 gzip 解 压 了 ， 所 以 可 以 不 用 设 
这 个 值 ,保持 系统 默认 即 可 。 


gzip_proxied 


语法 :*gzip_proxied [off|expired|no-cache|no- 
store|private|no last modified|no etag|auth|any] ...* 


默认 值 :*gzip_proxied off* 


作用 域 :*http, server, location* 


Nginx 作 为 反 向 代理 的 时 候 启 用 ， 开 和 启 或 者 关闭 后 端 服务 器 返回 的 结果 ， 匹 配 的 前 提 


务 器 必须 要 返回 包含 "Via" 的 header 头 。 


off - 关闭 所 有 的 代理 结果 数据 的 压 

e expired - 启用 压缩 ， ae "Expires" 头 信息 

e no-cache - 启用 压缩 ， 如 果 header 头 中 包含 "Cache-Control:no-cache" 头 信息 
e no-store - 启用 压缩 ， 如 果 header 头 中 包含 "Cache-Control:no-store" 头 信 息 
e private - 启用 压缩 ， 如 果 header 头 中 包含 "Cache-Control:private" 头 信息 

e no last modified - 启用 压缩 ,如 果 header 头 中 不 包含 "Last-Modified" 头 信息 

e no etag- 启用 压缩 ,如 果 header 头 中 不 包含 "ETag" 头 信息 

e auth - 启用 压缩 , 如果 header 头 中 包含 "Authorization" 头 信息 

。 any - 无 条 件 启 用 压缩 


gzip_types 

语法 :*gzip_types mime-type [mime-type ...]* 

默认 值 :*gzip_types text/html* 

作用 域 :*http, server, location* 

匹配 MIME 类 型 进行 压缩 ，〈 无 论 是 否 指定 ) "text/html" 类 型 总 是 会 被 压缩 的 。 


注意 : 如 果 作 为 http server 来 使 用 ， 主 配置 文件 中 要 包含 文件 类 型 配置 文件 


http 
{ 
include conf/mime.types; 
} 
如 果 你 希 记 压缩 常规 的 文件 类 型 ， 可 以 写成 这 个 祥子 
http 
{ 
: include conf/mime. types; 
: gzip on; 
: gzip min length 1000; 
: gzip buffers 4 8k; 


: gzip http version 1.1; 


是 后 端 服 


: gzip_types text/plain application/x-javascript text/css text/html application/xml 
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HttpHeaders 模 块 


本 模板 可 以 设置 HTTP 报 文 的 头 标 。 


示例 
: expires 24h; 
: expires 0; 
: expires -1; 
: expires epoch; 


: add header Cache-Control private; 
BA 
AT 


e [#add_header add_header] 
e [#expires expires] 


增加 头 标 

语法 : *add_header name value* 

默认 值 : *none* 

作用 域 : *http, server, location* 

当 HTTP 应 答 状 态 码 为 200、204、301、302 或 304 的 时 候 ， 增 加 指定 的 HTTP 头 标 。 


其 中 头 标 的 值 可 以 使 用 变量 。 


expires 

语法 : *expires [time|epoch|max|off]* 
默认 值 : *expires off* 

作用 域 : *http, server, location* 


使 用 本 指令 可 以 控制 HTTP 应 答 中 的 "Expires” 和 "Cache-Control" 的 头 标 ， 《起 到 控制 页 面 缓存 
的 作用 ) 。 


可 以 在 time 值 中 使 用 正 数 或 负数 。“Expires" 头 标的 值 将 通过 当前 系统 时 间 加 上 您 设 定 的 time 
值 来 获得 。 


epoch 指定 "Expires" 的 值 为 1 January, 1970, 00:00:01 GMT, 


max 指定 “Expires” 的 值 为 31 December 2037 23:59:59 GMT, "Cache-Control" B5 44 7j 10 
年 。 


-1 指定 “Expires” 的 值 为 服务 器 当前 时 间 -1s, 即 永远 过 期 
“Cache-Control” 头 标的 值 由 您 指定 的 时 间 来 决定 : 


. 负数 : Cache-Control: no-cache 
e. IE2A EXE : Cache-Control: max-age = £ E 为 您 指定 时 间 的 秒 数 。 


"off" 表示 不 修改 “Expires" 和 “Cache-Control” 的 值 


References 
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Httplndex 模 块 

语法 :*index file [file...]* 
默认 值 :*index index.htm|* 
作用 域 :*http, server, location* 


该 指 合用 来 指定 用 来 做 默认 文档 的 文件 名 ， 可 以 在 文件 名 处 使 用 变量 。 如 果 您 指定 了 多 个 文 
件 ， 那 么 将 按照 您 指定 的 顺序 逐个 查找 。 可 以 在 列表 末尾 加 上 一 个 绝对 路 径 名 的 文件 。 


示例 : 


index index.$geo.html  index.O.html  /index.html; 


参见 


z 
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HttpLimit zone 


本 模块 可 以 针对 和 条件， 进行 会 话 的 并 发 连接 数控 制 。 (例如 : 限制 每 个 IP 的 并 发 连接 数 。) 
置 示例 


http { 
: limit zone one $binary remote addr 10m; 


: server ( 


: location /download/ { 
: limit conn one 1; 


BA 
A TI 
e [#limit_zone limit zone] 
e [flimit conn limit conn] 
limit zone 
语法 : "limit zone zone name $variable the size* 
默认 值 : *no 
作用 域 : *http* 


本 指令 定义 了 一 个 数据 区 ， 里 面 记 录 会 话 状态 信息 。 
$variable 定义 判断 会 话 的 变量 ; the. size 定义 记录 区 的 总 容量 。 


例子 


limit_zone one $binary_remote_addr 10m; 


定义 一 个 叫 “one” 的 记录 区 ， 总 容量 为 10M， 以 变量 $binary remote addr 作为 会 话 的 判断 基 
准 〈 即 一 个 地 址 一 个 会 话 ) 。 


您 可 以 注意 到 了 ， 在 这 里 使 用 的 是 $binary_remote addr 而 不 是 $remote_addr. 


$remote addr 的 长 度 为 7 至 15 bytes， 会 话 信息 的 长 度 为 32 9X 64 bytes, 而 
$binary remote addr 的 长 度 为 4 bytes， 会 话 信息 的 长 度 为 32 bytes. 


当 区 的 大 小 为 1M 的 时 候 ， 大 约 可 以 记录 32000 个 会 话 信息 〈 一 个 会 话 占 用 32 bytes) 。 


limit_conn 

语法 : "limit conn zone name the size* 
默认 值 : *no* 

作用 域 : *http, server, location* 


指定 一 个 会 话 最 大 的 并 发 连接 数 。 当 超过 指定 的 最 发 并 发 连接 数 时 ， 服 务 器 将 返回 "Service 
unavailable" (503)。 


例子 : 


limit zone one $binary remote addr 10m; 


: server ( 
: location /download/ { 
: limit conn one 1; 


定义 一 个 叫 “one” 的 记录 区 ， 总 容量 为 10M， 以 变量 $binary remote addr 作为 会 话 的 判断 基 
准 〈 即 一 个 地 址 一 个 会 话 ) 。 限制 /download/ 目录 下 ， 一 个 会 话 只 能 进行 一 个 连接 。 简单 
点 ， 就 是 限制 /download 目录 下 ， 一 个 IP 只 能 发 起 一 个 连接 ， 多 过 一 个 ， 一 律 503。 
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HttpLimitReqest45" 


This module allows you to limit the number of requests for a given session, or as a special 
case, with one address. 


Restriction done using leaky bucket. 


Example Configuration 


http { 
limit req zone 3$binary remote addr zone=one:10m rate=1r/s; 


server { 


location /search/ { 


limit req zone-cone burst=5; 


$ IR 4P 


Syntax:*limit req zone $session variable zone-name of zone:size rate-rate* 
Default:*none* 
Context:*http* 


The directive describes the area, which stores the state of the sessions. The values of the 
sessions is determined by the given variable. Example of usage: 


limit req zone 3$binary remote addr zone=one:10m rate=1r/s; 


In this case, the session state is allocated 10MB as a zone called "one", and the average 
speed of queries for this zone is limited to 1 request per second. 


The sessions are tracked per-user in this case, but note that instead of the variable 
$remote_addr, we've used the variable $binary_remote_addr, reducing the size of the state 
to 64 bytes. A 1 MB zone can hold approximately 16000 states of this size. 


The speed is set in requests per second or requests per minute. The rate must be an 
integer, so if you need to specify less than one request per second, say, one request every 
two seconds, you would specify it as "30r/m". 


Syntax:*limit_req zone=zone burst=burst [nodelay]* 
Default:*none* 
Context:*http, server, location* 


The directive specifies the zone (zone) and the maximum possible bursts of requests 
(burst). If the rate exceeds the demands outlined in the zone, the request is delayed, so that 
queries are processed at a given speed. Excess requests are delayed until their number 
does not exceed a specified number of bursts. In this case the request is completed the 
code "Service unavailable" (503). By default, the burst is zero. 


For example, the directive 
limit req zone $binary_remote_addr zone=one:10m rate-1r/s; 


server { 
location /search/ ( 
limit req Zone=one burst=5; 
} 


allows a user no more than 1 request per second on average, with bursts of no more than 5 
queries. If the excess requests within the limit burst delay are not necessary, you should use 
the nodelay: 


limit_req zone=one burst=5 nodelay; 


HttpLog 模 块 
ngx http log module 实例 


log format gzip '$remote_addr - $remote user [$time local] ' 
: '"$request" $status $bytes sent ' 

: '"$http referer" "$http user agent" "$gzip_ratio"'; 

access log /spool/logs/nginx-access.log gzip buffer=32k; 


S 

A TI 
e access log 
e log format 


access log 


语法 : *access log path [format [buffer=size | off ] 默认 值 : access log log/access.log 
combined* 


作用 域 : *http, server, location* 


指令 access log 指派 路 径 、 格 式 和 缓存 大 小 。 参 数 "off" 将 清除 当前 级 别 的 所 有 access log 
指令 。 如 果 未 指定 格式 ， 则 使 用 预 置 的 "combined" 格式 。 缓 存 不 能 大 于 能 写 入 磁盘 的 文件 的 
最 大 大 小 。 在 FreeBSD 3.0-6.0 ， 缓 存 大 小 无 此 限制 。 


log_format 


语法 : *log_format name format [format ...]* 
默认 值 : *log format combined "..."* 
作用 域 : *http*server 


Directive log_format describes the format of a log entry. Besides general variables in the 
format it is possible to use variables which exist only at the moment of record into the log: 


e $body_bytes_ sent, the number of bytes, transmitted to client minus the response 
headers, variable is compatible with parameter %B of module Apache's mod_log_config 
(this was called $apache bytes sent, before version 0.3.10) 

e $bytes sent, the number of bytes, transmitted to client 

e $connection, the number of connection 

e $msec, the time with an accuracy to microseconds at the moment of the log entry 

e $pipe, "p" if request was pipelining 

e $request_length, the length of the body of the request 


e $request_time, the time of working on request in seconds 
e $status, status of answer 


e $time_local, local time into common log format. 


The headers, transmitted to client, begin from the prefix "senthttp", for example, 
$sent_http_content_range. 


In the configuration there is always a predetermined format "combined": 


log format combined '$remote_addr - $remote user [$time_local] ' 
'"$request" $status $apache bytes sent ' 
'"$http referer" "$http user agent"'; 


参考 
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map 


This module allows you to classify, or map a set of values into a different set of values and 
store the result in a variable. 


Example: 


map $http_host $name { 
hostnames; 


default 0; 


example.com 1; 
* example.com abe 
test.com 2: 
*.test.com 25 
.Site.com 3; 


One use for this would be to use a mapping in place of writing lots of server/location 
directives or redirects: 


map $uri $new { 


default http://www. domain.com/home/; 
/aa http://aa.domain.com/; 
/bb http://bb.domain.com/; 
/john http://my.domain.com/users/john/; 
H 
server { 
server name www.domain.com; 
rewrite ^ $new redirect; 
} 
指令 
H T 
map 


syntax:*map $var1 $var2 ( ... }* 
default:*none* 
context:*http* 


map defines the mapping table which will be used to set a variable. There are three special 
parameters: 


e default — defines the value to be used where no match is found. 


e hostnames — it allows for an easier matching of values like host names, names with a 
starting dot may match exact host names and host names ending with the value, for 
example: 


*.example.com 1; 


Instead of two entries 


example.com dL? 
* example.com 1; 


we can use only one 


. example.com dL? 
e include — include values from a file. Multiple includes may be used. 


map hash max size 


syntax:*map hash max size number* 
default:*map hash max size 2048* 
context:*http* 


The directive sets the maximum size of a hash table to hold the variable map. For more 
details see the descriptions of hash settings Optimization section . 


map hash bucket size 
syntax:*map hash bucket size n* 
default:*map hash bucket size 32/64/128* 
context:*http* 


The directive sets the maximum size in a hash table to map variables. The default value 
depends on the size of the cache line processor. More see in the descriptions of hash 
settings in the Optimization section . 


References 


Original Documentation 


Memcached 
你 可 以 利用 本 模块 来 进行 简单 的 缓存 以 提高 系统 效率 。 本 模块 计划 在 未 来 进行 扩展 。 


配置 示例 


server { 

: location / { 

: set $memcached key $uri; 

: memcached pass name : 11211; 

: default_type text/html; 

: error page 404 = /fallback; 


: location = /fallback { 
proxy_pass backend; 


BA 
AT 


e [#memcached_pass memcached pass] 

e [£memcached connect timeout memcached connect timeout] 
e [f£memcached send timeout memcached send timeout] 

e [£memcached read timeout memcached read timeout] 

e [fmemcached buffer size memcached buffer size] 

e [fmemcached next upstream memcached next upstream] 


变量 


e $memcached key 


memcached pass 

语法 : *memcached pass [ name:port ]* 

SUA & : *none* 

作用 域 : *http, server, location* 

The backend should set the data in memcached. The memcached key is "/uri?args". 


Since 0.5.9 the memcached key is now in $memcached key . 


memcached connect timeout 


语法 : *memcached connect timeout [ time ]* 
默认 值 : *60000* 
作用 域 : *http, server, location* 


The timeout for connecting to memcached, in milliseconds. 


memcached_read_timeout 
语法 : *memcached_read_timeout [ time ]* 
默认 值 : *60000* 

作用 域 : *http, server, location* 


The timeout for reading from memcached, in milliseconds. 


memcached_send_timeout 
语法 : *memcached_send_timeout [ time ]* 
默认 值 : *60000* 

作用 域 : *http, server, location* 


The timeout for sending to memcached, in milliseconds. 


memcached_buffer_size 
语法 : *memcached_buffer_size [ size ]* 
默认 值 see getpagesize(2) 

作用 域 : *http, server, location* 


The recv/send buffer size, in bytes. 


memcached_next_upstream 


语法 : *memcached next upstream [ error | timeout | invalid response | not found | off ]* 
默认 值 : *error timeout* 


作用 域 : *http, server, location* 


Which failure conditions should cause the request to be forwarded to another upstream 
server? Applies only when the value in memcached_pass is an upstream with two or more 
servers. 


HttpProxy 模 块 


This module makes it possible to transfer requests to another server. 此 模块 专 伺 闻 请 求 导向 
其 它 服 务 . 


It is an HTTP/1.0 proxy without the ability for keep-alive requests yet. 这 是 种 HTTP/1.0 版 本 
的 无 请 求 保 持 代 理 . 


(As a result, backend connections are created and destroyed on every request.) Nginx talks 
HTTP/1.1 to the browser and HTTP/1.0 to the backend server. As such it handles keep-alive 
to the browser. 


(因为 每 个 请 求 都 是 在 后 台 连 接 中 创建 和 销毁 的 ) Nginx 和 浏览 器 使 用 HTTP/1.1 进行 对 话 ， 而 
在 后 台 服 务 中 使 用 HTTP/1.0; 


示例 
location / { 
: proxy pass http://localhost :8000; 
: proxy_set_header X-Real-IP $remote_addr; 


} 


注意 一 点 , 当 使 用 HTTP PROXY 模块 时 (或 者 甚至 是 使 用 FastCGI 时 ), 用 户 的 整个 请 求 会 在 
nginx 中 缓冲 直至 传送 给 后 端 被 代理 的 服务 器 .因此 ,上 传 进度 的 测算 就 会 运作 得 不 正确 ,如 果 它 
们 通过 测算 后 端 服务 器 收 到 的 数据 来 工作 的 话 


定向 器 . Directives 


e [#proxy_buffer_size proxy_buffer_size] 

e [#proxy_buffering proxy_buffering] 

e [#proxy_buffers proxy_buffers] 

e [#proxy_busy_buffers_size proxy busy buffers size] 

e [Zproxy connect timeout proxy connect timeout] 

e [Zproxy headers hash bucket size proxy headers hash bucket size] 
e [Zproxy headers hash max size proxy headers hash max size] 
e [Zproxy hide header proxy hide header] 

e [Zproxy ignore client abort proxy ignore client abort] 

e [Zproxy intercept errors proxy intercept errors] 

e [fproxy max temp file size proxy max temp file size] 

e [Zproxy method proxy method] 

e [Zproxy next upstream proxy next upstream] 

e [Zproxy pass proxy pass] 

e [Zproxy pass header proxy pass header] 


e [#proxy_pass_request_body proxy pass request body] 

e [Zproxy pass request headers proxy pass request headers] 
e [Zproxy redirect proxy redirect] 

e [Zproxy read timeout proxy read timeout] 

e [Zproxy redirect errors proxy redirect errors] 

e [Zproxy send lowat proxy send lowat] 

e [Zproxy send timeout proxy send timeout] 

e [Zproxy set body proxy set body] 

e [Zproxy set header proxy. set header] 

e [Zproxy store proxy store] 

e [fproxy store access proxy store access] 

e [fproxy temp file write size proxy temp file write size] 

e [£proxy temp path proxy temp path] 

e [f£proxy upstream fail timeout proxy. upstream fail timeout] 
e [fproxy upstream max fails proxy upstream max fails] 


BR Variables 


e [#var_proxy_host var proxy host] 

e [f£var proxy port var proxy port] 

e [£var proxy add x forwarded for var proxy add x forwarded for] 
e [fvar proxy remote addr var proxy remote addr] 


proxy buffer size 

i&ik:*proxy buffer size the size* 

EI^ f&:*proxy. buffer. size 4k/8k* 

上 下 文 :*http, server, location* 

该 指 合 设置 缓冲 区 大 小 ,从 被 代理 的 后 端 服 务 器 取得 的 响应 内 容 ,会 先 读 取 放 置 到 这 里 . 
小 的 响应 header 通 常 位 于 这 部 分 响应 内 容 里 边 . 


默认 来 说 ,该 缓冲 区 大 小 等 于 指令 proxy buffers 所 设置 的 ;但 是 ,你 可 以 把 它 设置 得 更 小 . 
proxy_buffering 
语法 :*proxy_buffering on|off* 


默认 值 :*proxy_buffering on* 


上 下 文 :*http, server, location* 


该 指令 开启 从 后 端 被 代理 服务 器 的 响应 内 容 缓 冲 . 


如 果 绥 冲 区 开启 ,nginx 假 定 被 代理 的 后 端 服 务 器 会 以 最 快速 度 响应 ,并 把 内 容 保 存在 由 指 
a proxy_buffer_size 和 proxy_buffers 指定 的 缓冲 区 里 边 . 


如 果 响 应 内 容 无 法 放 在 内 存 里 边 ,那么 部 分 内 容 会 被 写 到 磁盘 上 . 
如 果 缓 冲 区 被 关闭 了 ,那么 响应 内 容 会 按照 获取 内 容 的 多 少 立刻 同步 传送 到 客户 端 
nginx 不 尝试 计 算 被 代理 服务 器 整个 响应 内 容 的 大 小 ,nginx 能 从 服务 器 接受 的 最 大 数据 ,是 由 指 


a proxy_buffer_size 指定 的 . 


proxy_buffers 


语法 :*proxy_buffers the number is size;* 

EI^ f&:*proxy. buffers 8 4k/8k;* 

上 下 文 :*http, server, location* 

该 指 合 设 置 缓 冲 区 的 大 小 和 数量 ,从 被 代理 的 后 端 服务 器 取得 的 响应 内 容 , 会 放置 到 这 里 . 默认 
情况 下 ,一 个 缓冲 区 的 大 小 等 于 页 面 大 小 ,可 能 是 4K 也 可 能 是 8K, 这 取决 于 平台 


proxy_busy_buffers_size 
i&ik:*proxy busy buffers size size;* 

FAM &:*proxy busy buffers size proxy buffer size 2; 
上 下 文 :*http, server, location, if* 


TODO: Description. 


proxy_connect_timeout 


语法 :*proxy_connect timeout timeout_in_seconds* 
上 下 文 :*http, server, location* 


This directive assigns a timeout for the connection to the proxyserver. This is not the time 
until the server returns the pages, this is the [#proxy_read_timeout proxy_read timeout] 
statement. If your proxyserver is up, but hanging (e.g. it does not have enough threads to 
process your request so it puts you in the pool of connections to deal with later), then this 
statement will not help as the connection to the server has been made. It is necessary to 
keep in mind that this time out cannot be more than 75 seconds. 


proxy_headers_hash_bucket_size 


i&ik:*proxy headers hash bucket size size;* 
FAM &:*proxy headers hash bucket size 64;* 
上 下 文 :*http, server, location, if* 


This directive sets the bucket size of the hashtable. 
TODO: Better description 


proxy_headers_hash_max_size 


i&ik:*"proxy headers hash max size size;* 
EA f&:*proxy headers hash max size 512;* 
上 下 文 :*http, server, location, if* 


This directive sets the maximum size of the hashtable. 
TODO: Better description 


proxy_hide_header 


语法 :*proxy_hide_header the_header* 
上 下 文 :*http, server, location* 


nginx does not transfer the "Date", "Server", "X-Pad" and "X-Accel-..." header lines from the 
proxied server response. The proxy_hide_header directive allows to hide some additional 
header lines. But if on the contrary the header lines must be passed, then the 

proxy_pass_header should be used. For example if you want to hide the MS- 
OfficeWebserver and the AspNet-Version: 


location / { 
: proxy hide header X-AspNet-Version; 
: proxy hide header MicrosoftOfficeWebServer; 


} 


This directive can also be very helpful when using X-Accel-Redirect. For example, you may 
have one set of backend servers which return the headers for a file download, which 
includes X-Accel-Redirect to the actual file, as well as the correct Content-Type. However, 
the Redirect URL points to a filleserver which hosts the actual file you wish to serve, and that 
server sends its own Content-Type header, which might be incorrect, and overrides the 
header sent by the original backend servers. You can avoid this by adding the 
proxy_hide_header directive to the fileserver. Example: 


location / { 
: proxy_pass http://backend_servers; 


location /files/ { 

: proxy pass http://fileserver; 

: proxy hide header Content-Type; 
} 


proxy_ignore_client_abort 


* 


i&ik:*proxy ignore client abort [ on|off ] 
Bk i f&:*proxy. ignore client abort off* 
上 下 文 :*http, server, location* 

Available since: 0.3.36 

如 果 客 户 端 断 开 请 求 ,也 保持 后 端的 下 载 


proxy_intercept errors 
语法 :*proxy_intercept_errors [ onloff ]* 
默认 值 :*proxy_intercept_errors off* 


上 下 文 :*http, server, location* 


This directive decides if nginx will intercept responses with HTTP status codes of 400 and 


higher. 


By default all responses will be sent as-is from the proxied server. 


If you set this to on then nginx will intercept status codes that are explicitly handled by an 


error_page directive. Responses with status codes that do not match an error_page 


directive will be sent as-is from the proxied server. 


proxy_max_temp_file_size 
i&ik:*proxy max temp file size size;* 
默认 值 :*proxy_ max temp file size 1G;* 
上 下 文 :*http, server, location, if* 


Available since: 0.1.8 
TODO: Description. 


proxy_method 


语法 :*proxy_method [method]* 

默认 值 :*Noner* 

上 下 文 :*http, server, location* 

Used to allow the proxying of additional HTTP methods. 


Note: at this time, Nginx only appears to allow a single instance of this directive and it only 
accepts a single argument (method) so it's not clear how useful this might be for proxying to 
things like Subversion. 


Example: 


: proxy_method PROPFIND; 


proxy_next_upstream 


语法 :*proxy_next_upstream [error|timeout|invalid_header|http_500|http_503|http_404|off]* 
默认 值 :*proxy_next_upstream error timeout* 

上 下 文 :*http, server, location* 

Directive determines, in what cases the request will be transmitted to the next server: 


e error — an error has occurred while connecting to the server, sending a request to it, or 
reading its response; 

e timeout — occurred timeout during the connection with the server, transfer the requst or 
while reading response from the server; 

e invalid header — server returned a empty or incorrect answer; 

e http 500 — server returned answer with code 500 

e http 503 — server returned answer with code 503 

e http 404 — server returned answer with code 404 

e off — it forbids the request transfer to the next server 


Transferring the request to the next server is only possible when nothing has been 
transferred to the client -- that is, if an error or timeout arises in the middle of the transfer of 
the request, then it is not possible to retry the current request on a different server. 


proxy pass 


i&ik:*proxy pass URL* 


默认 值 :*no* 
上 下 文 :*location, if in location* 


This directive sets the port or socket, on which listens to the proxied server, and the URI, to 
which will be reflected location. 


Port can be indicated in the form of the name of hostname or address and port, for example, 


proxy_pass http://localhost:8000/uri /; 


and socket -- in the form of unix of socket: 


proxy_pass http://unix:/tmp/backend.socket:/uri /; 


Path is indicated after the word unix and is concluded between two colons. 


With the transfer of request to server part URI, which corresponds to location, is substituted 
to URI, indicated in directive proxy_pass. 


But there are two exceptions to this rule, when it is not possible to determine that replaced 
location: 


e if the location is assigned by regular expression; 
e if inside proxied location with the help of directive rewrite changes URI and with this 
configuration will be precisely processed request (break): 


location /name/ { 
: rewrite /name/([4/] +) /users?name=$1 break; 
: proxy_pass http://127.0.0.1; 


For these cases of URI it is transferred without the mapping. 


Furthermore, it is possible to indicate so that URI demand it would be transferred in the 
same form, as it sent client, but not v in the processed form. 


During the working: 


e two or by more slashes are converted into one slash: "//" -- "/"; 
e references to the current directory are removed: "/./" -- "/"; 
e references to the previous catalog are removed: "/dir /../" -- "/". 


If on server it is necessary to transmit URI in the unprocessed form, then for this in directive 
proxy. pass it is necessary to indicate URL server without URI: 


location /some/path/ { 
: proxy pass http://127.0.0.1; 


proxy pass header 


i&ik:*proxy pass header the name* 
上 下 文 :*http, server, location* 
This directive allows transferring header-lines forbidden for response. 


For example: 


location / { 
: proxy_pass_header Server; 
: proxy pass header X-MyHeader; 


} 


proxy_pass_request_body 
i&ik:*proxy pass request body [ on | off ] ;* 
SUA &:*proxy pass request body on;* 

上 下 文 :*http, server, location* 


Available since: 0.1.29 
TODO: Description. 


proxy_pass_request_headers 
i&ik:*proxy pass request headers [ on | off ] ;* 
FAN &:*proxy pass request headers on;* 

上 下 文 :*http, server, location* 

Available since: 0.1.29 


TODO: Description. 


proxy_redirect 


语法 :*proxy_redirect [ default|off|redirect replacement ]* 


默认 值 :*proxy_redirect default* 


上 下 文 :*http, server, location* 


This directive sets the text, which must be changed in response-header "Location" and 
"Refresh" in the response of the proxied server. 


Let us suppose the proxied server returned line 


Location: http://localhost:8000/two/some/uri/ 


The directive 


proxy. redirect http://localhost:8000/two/ http://frontend/one/; 


will rewrite this line in the form Location: http://frontend/one/some/uri/ 


In the replaceable line it is possible not to indicate the name of the server: 


proxy redirect http://localhost:8000/two/ /; 


then the basic name of server and port is set, if it is different from 80. 


The change by default, given by the parameter "default", uses the parameters of directives 
location and proxy pass. 


Therefore two following configurations are equivalent: 


location /one/ { 


: proxy pass http://upstream: port/two/; 

: proxy redirect default; 

} 

location /one/ { 

: proxy pass http://upstream: port/two/; 

: proxy redirect http://upstream:port/two/ /one/; 
} 


In the replace line, it is possible to use some variables: 


proxy_redirect http://localhost:8000/ http://$host:$server port/; 


This directive repeated some times: 


: proxy redirect default; 
: proxy redirect http://localhost:8000/ le 
: proxy redirect http://www. example .com/ /i 


The parameter off forbids all proxy redirect directives at this level: 


: proxy redirect off; 

: proxy redirect default; 

: proxy redirect http://localhost:8000/ 75 
: proxy redirect http: //www.example.com/ ie 


With the help of this directive it is possible to add the name of host for relative redirect, 
issued by the proxied server: 


proxy_redirect if ie 


proxy_read_timeout 

语法 :*proxy_read timeout the_time* 
默认 值 :*proxy_read timeout 60* 

上 下 文 :*http, server, location* 


This directive sets the read timeout for the response of the proxied server. It determines how 
long NGINX will wait to get the response to a request. The timeout is established not for 
entire response, but only between two operations of reading. 


In contrast to [#proxy_connect_timeout proxy connect timeout] , this timeout will catch a 
server that puts you in it's connection pool but does not respond to you with anything beyond 
that. Be careful though not to set this too low, as your proxyserver might take a longer time 
to respond to requests on purpose (e.g. when serving you a report page that takes some 
time to compute). You are able though to have a different setting per location, which enables 
you to have a higher proxy_read_timeout for the report page's location. 


If the proxied server nothing will communicate after this time, then nginx is shut connection. 


proxy_redirect_errors 


Deprecated. Use proxy intercept errors . 


proxy send lowat 
i&ik:*proxy send lowat [ on | off ]* 
默认 值 :*proxy_send lowat off;* 

上 下 文 :*http, server, location, if* 


This directive set SO SNDLOWAT. 
This directive is only available on FreeBSD 


proxy_send_timeout 
i&ik:*proxy send timeout time_in_seconds* 
EA f&:*proxy send timeout 60* 

上 下 文 :*http, server, location* 


This directive assigns timeout with the transfer of request to the proxy server. Time out is 
established not on entire transfer of request, but only between two operations of record. If 
after this time the proxy server will not take new data, then nginx is shut the connection 


proxy_send_lowat 
i&ik:*proxy set body [on | off ]* 
默认 值 :*proxy_set body off;* 

上 下 文 :*http, server, location, if* 


Available since: 0.3.10 
TODO: Description. 


proxy_set_header 


语法 :*proxy_set_header header value* 
默认 值 :*Host and Connection* 
上 下 文 :*http, server, location* 


This directive allows to redefine and to add some request header lines which will be 
transferred to the proxied server. 


As the value it is possible to use a text, variables and their combination. 


This directive is inherited from the previous level when at this level are not described their 
directives proxy_set_header . 


By default only two lines will be redefined: 


proxy_set_header Host $proxy_host; 
proxy_set_header Connection Close; 


The unchanged request-header "Host" can be transmitted like this: 


proxy_set_header Host $http_host; 


However, if this line is absent from the client request, then nothing will be transferred. 


In this case it is better to use variable $host, it's value is equal to the name of server in the 
request-header "Host" or to the basic name of server, if there is no line: 


proxy_set_header Host $host; 


Furthermore, it is possible to transmit the name of server together with the port of the 
proxied server: 


proxy_set_header Host $host:$proxy_port; 


proxy_store 

i&ik:*proxy store [on | off | path]* 
EI f& :*proxy. store off* 

上 下 文 :*http, server, location* 


This directive sets the path in which upstream files are stored. The parameter "on" preserves 
files in accordance with path specified in directives alias or root. The parameter "off" forbids 
storing. Furthermore, the name of the path can be clearly assigned with the aid of the line 
with the variables: 


proxy_store /data/www$original_uri; 


The time of modification for the file will be set to the date of "Last-Modified" header in the 
response. To be able to safe files in this directory it is necessary that the path is under the 
directory with temporary files, given by directive proxy_temp_path for the data location. 


This directive can be used for creating the local copies for dynamic output of the backend 
which is not very often changed, for example: 


location /images/ { 


root /data/www; 
: error page 404 = /fetch$uri; 
} 
location /fetch { 
: internal; 
: proxy pass http://backend; 
: proxy store on; 
: proxy store access user:rw group:rw all:r; 
: proxy temp path /data/temp; 
: alias /data/www; 
} 


To be clear proxy_store is not a cache, it's rather mirror on demand. 


proxy_store_access 


i&ik:*proxy store access users:permissions [users:permission ...]* 
FAM &:*proxy store access user:rw* 
上 下 文 :*http, server, location* 


This directive assigns the permissions for the created files and directories, for example: 


proxy store access user:rw group:rw all:r; 


If any rights for groups or all are assigned, then it is not necessary to assign rights for user: 


proxy store access group:rw all:r; 


proxy temp file write size 
i&ik:*proxy temp file write size size;* 

默认 值 :*proxy_temp file write size proxy. buffer size 2; 
上 下 文 :*http, server, location, if* 


TODO: Description. 


proxy_temp_path 


i&ik:*proxy temp path dir-path [ level1 [ level2 [ level3 ] ;* 


默认 值 :*$NGX_PREFIX/proxy_temp controlled by --http-proxy-temp-path at ./configure 
stage* 


上 下 文 :*http, server, location* 


This directive works like client_body_temp_path to specify a location to buffer large proxied 
requests to the filesystem. 


proxy_upstream_fail_timeout 


Changed in 0.5.0 to deprecated. 
Please use the fail_timeout parameter of server Directive from the upstream module. 


proxy_upstream_max_fails 


Changed in 0.5.0 to deprecated. 
Please use the max_fails parameter of server Directive from the upstream module. 


Variables 


In module ngx_http_proxy_module there are some built-in variables, which can be used for 
the creation of headers with the help of the proxy set header directive: 


$proxy host: the name of proxied host and port; 
$proxy port:: the port of proxied host; 


$proxy add x forwarded for:: equivalent to client request-header "X-Forwarded-For" and to 
variable added to it through the comma 


$remote addr:: But if there is no line "X-Forwarded-For" in the client request, then variable 
$proxy add x forwarded for is equal to variable sremote addr . 


References 


Original Documentation 


Questions 


e Is it possible to have the proxy use a client SSL certificate to communicate with the 
server being proxied? | am in the situation where | want to secure the proxy <-> 
application server connection. Another solution could be to use SSL only with a custom 
header checked at each connection in the application server, but doing it at the protocol 
level would be nicer. 


e NginxHttpProxyModule#preview 原文 


HttpRewrite 模 块 


This module makes it possible to change URI using regular expressions, and to redirect and 
select configuration depending on variables. 


该 模块 允许 使 用 正则 表达 式 改变 URI， 并 且 根 据 变量 来 转向 以 及 选择 配置 。 


fthe directives of this module are given at the server level, then they are carried out before 
the location of the request is determined. If in that selected location there are further rewrite 
directives, then they also are carried out. If the URI changed as a result of the execution of 
directives inside location, then location is again determined for the new URI. 


如 果 在 server 级 别 设 置 该 选项 ， 那 么 他 们 将 在 location 之 前 生效 。 如 果 在 location 还 有 更 进一步 
的 重 写 规则 ，location 部 分 的 规则 依然 会 被 执行 。 如 果 这 个 URI 重 写 是 因为 location 部 分 的 规则 
造成 的 ， 那 么 location 部 分 会 再 次 被 执行 作为 新 的 URI。 


This cycle can be repeated up to 10 times, after which Nginx returns a 500 error. 


这 个 循环 会 执行 10 次 ， 然 后 Nginx 会 返回 一 个 500 错 误 。 


Directives 


[#break break] 
[#if if] 
[#return return] 


[#rewrite rewrite] 
[#set set] 
[#uninitialized_variable_warn uninitialized_variable_warn] 


break 

语法 :*break* 

默认 值 :*hnone* 

作用 域 :*server, location, if* 

Completes the current set of rules. 作用 是 完成 当前 的 规则 列 


示例 : 


if ($slow) { 
: limit_rate 10k; 
: break; 


} 


if 


语法 :*if (condition) ( ... ¥ 


默认 :*none* 


作用 域 :*server, location* 


Checks the truth of a condition. If the condition evaluates to true, then the code indicated in 


the curly braces is carried out and the request is processed in accordance with the 


configuration within the following block. Configuration inside directive if is inherited from the 


previous level. 


They can be assigned as the condition: 


the name of variable; false values are: empty string "", or any string starting with "0"; 
the comparison of variable with the line with using the = and != operators; 
pattern matching with regular expressions using the symbols ~* and ~ : 

~ is case-sensitive match; 
CURES, (eA) SBR 

~* specifies a case-insensitive match (firefox matches FireFox) 
~ 大 小 写 不 敏感 的 符合 (firefox 4 FireFox) 

I~ and !~* mean the opposite, "doesn't match" 
!~ 和 !~* 代 表 相 反 ，“ 不 符合 ” 
checking for the existence of a file using the -f and !-f operators; 使 用 -f 以 及 !-f 检 测 一 
个 文件 是 否 存 在 
checking existence of a directory using the -d and !-d operators; 使 用 -d 以 及 !-d 检 测 一 
个 目录 是 否 存 在 
checking existence of a file, directory or symbolic link using the -e and !-e operators; 
使 用 -e 以 及 !-e 检 测 是 否 存在 一 个 文件 ， 一 个 目录 或 者 一 个 符号 链接 。 


checking whether a file is executable using the -x and !-x operators. 使 用 -x 以 及 !-x 检 
测 一 个 文件 是 否 可 执行 


Parts of the regular expressions can be in parentheses, whose value can then later be 


accessed in the $1 to >$9 variables. 


Examples of use: 


if ($http_user_agent ~ MSIE) { 
: rewrite ^(.*)$ /msie/$1 break; 


} 
if ($http_cookie -* "id=([4;] +)(?:;|$)" ) 1 
: set $id $1; 


} 
if ($request_method = POST ) { 
: return 405; 


if (!-f $request_filename) { 
: break; 
: proxy pass http://127.0.0.1; 


if ($slow) { 
: limit rate 10k; 


if ($invalid referer) { 
: return 403; 
} 


The value of the built-in variable $invalid referer is given by the directive valid_referers. 


return 


语法 :*return code* 
默认 值 :*none* 
作用 域 :*server location, if* 


This directive concludes execution of the rules and returns the status code indicated to 
client. It is possible to use the following values: 204, 400, 402-406, 408, 410, 411, 413, 416 
and 500-504. Furthermore, nonstandard code 444 closes the connection without sending 
any headers. 


这 个 指令 根据 规则 的 执行 情况 ， 返 回 一 个 状态 值 给 客户 端 。 可 使 用 值 包括 : 204, 400, 402- 
406，408，410，411，413，416 以 及 500-504。 也 可 以 发 送 非 标准 的 444 代 码 -未 发 送 任何 头 
信息 下 结束 连接 。 


rewrite 


语法 :*rewrite regex replacement flag* 
默认 :*none* 
作用 域 :*server location, if* 


This directive changes URI in accordance with the regular expression and the replacement 
string. Directives are carried out in order of appearance in the configuration file. 


这 个 指令 根据 表达 式 来 更 改 URI， 或 者 修改 字符 串 。 指 令 根 据 配置 文件 中 的 顺序 来 执行 。 


Be aware that the rewrite regex only matches the relative path instead of the absolute URL. 
If you want to match the hostname, you should use an if condition, like so: 


注意 重 写 表达 式 只 对 相对 路 径 有 效 。 如 果 你 想 配 对 主机 名 ， 你 应 该 使 用 ff 语句 ， 如 下 : 


if ($host ~* wwwN.(.*)) { 
: set $host_without_www $1; 
: rewrite ^(.*)$ http://$host_without_www$1 permanent; # $1 contains '/foo', not 'www.myd 


} 
si 一 一 起 








Flags make it possible to end the execution of rewrite directives. 


If the replacement string begins with nttp:// then the client will be redirected, and any 
further rewrite directives are terminated. 


Flags can be any of the following: 


e last - completes processing of rewrite directives, after which searches for corresponding 
URI and location 

e break - completes processing of rewrite directives 

e redirect - returns temporary redirect with code 302; it is used if the substituting line 
begins with http: // 

e permanent - returns permanent redirect with code 301 


Note that if an redirect is relative (has no host part), then when redirecting Nginx uses the 
"Host" header if the header match name of server name directive or the first name of 

server name directive, if the header does not match or is absent. If no server name is set, 
then the local hostname is used. If you want Nginx to always use the "Host" header, you can 
use a wildcard """ server name (but see the restrictions on doing so).Example: 


rewrite ^(/download/.*)/media/(.*)N..*$  $1/mp3/$2.mp3 last; 
rewrite ^(/download/.*)/audio/(.*)N..*$ $1/mp3/$2.ra last; 
return 403; 


But if we place these directives in location /download/, then it is necessary to replace flag 
"last" by "break", otherwise nginx will hit the 10 cycle limit and return error 500: 


location /download/ { 

: rewrite ^(/download/.*)/media/(.*)N..*$  $1/mp3/$2.mp3 break; 
: rewrite ^(/download/.*)/audio/(.*)N..*$ $1/mp3/$2.ra break; 
: return 403; 

} 


If in the line of replacement arguments are indicated, then the rest of the request arguments 
are appended to them. To avoid having them appended, place a question mark as the last 
character: 


: rewrite ^/users/(.*)$ /show?user=$1? last; 


注 : 对 花 括 号 ({ 和 } ) Rit, 他 们 既 能 用 在 重 定 向 的 正则 表达 式 里 ， 也 是 用 在 配置 文件 里 分 割 代 
码 块 , 为 了 避免 冲突 , 正则 表达 式 里 带 花 括 号 的 话 ， 应 该 用 双 引 号 (或 者 单 引号 ) 包围 。 比 
如 ， 要 将 类 似 以 下 的 url 


/photos/123456 


/path/to/photos/12/1234/123456. png 


可 以 用 以 下 方法 (注意 双 引 号 ): 

rewrite "/photos/([0-9] {2})([0-9] {2})([0-9] {2})" /path/to/photos/$1/$1$2/$1$2$3.png; 
SSS SSS en L 
set 


syntax:*set variable value* 
default:*none* 
context:*server, location, if* 


Directive establishes value for the variable indicated. As the value it is possible to use a text, 
variables and their combination. 


uninitialized_variable_warn 


syntax:*uninitialized_variable_warn on|off* 
default:*uninitialized_variable_warn on* 

context:*http, server, location, if* 

Enables or disables logging of warnings about noninitialized variables. 


Internally, the rewrite directives are compiled at the time the configuration file is loaded into 
internal codes, usable during the request by the interpreter. 


This interpreter is a simple stack virtual machine. For example, the directive: 


location /download/ { 
: if ($forbidden) { 
return 403; 


} 
if ($slow) { 
limit_rate 10k; 


H 
rewrite ^/(download/.*)/media/(.*)N..*$ /$1/mp3/$2.mp3 break; 


will be compiled into this sequence: 


: variable $forbidden 

: checking to zero 

: recovery 403 

: completion of entire code 
: variable $slow 

: checking to zero 

: checkings of regular expression 
: copying "/" 

: copying $1 

: copying "/mp3/" 

: copying $2 

: copying "..mpe" 


: completion of regular expression 
: completion of entire sequence 


Note that there is no code for directive limit rate, since it does not refer to module 
ngx http rewrite module. The "if" block exists in the same part of the configuration as the 
"location" directive. 


If $slow is true, then what's inside the "if" block is evaluated, and in this configuration 
limit rate it is equal to 10k. 


Directive: 


rewrite ^/(download/.*)/media/(.*)N..*$ /$1/mp3/$2.mp3 break; 


It is possible to reduce the sequence, if in the regular expression we include the first slash 
inside the parentheses: 


rewrite ^(/download/.*)/media/(.*)N..*$ $1/mp3/$2.mp3 break; 


then the sequence will appear like this: 


: checking regular expression 

: copying $1 

: copying "/mp3/" 

: copying $2 

: copying "..mpe" 

: completion of regular expression 
: completion of entire code 


References 


Original Documentation 


HttpSSI 模 块 


此 模块 处 理 服 务 器 端 包含 文件 (ssi) 的 处 理 . 列表 中 的 命令 当前 并 未 完全 支持 . 


配置 示例 


location / { 
: Ssi on; 


} 


Directives 


e [#ssi ssi] 

e [#ssi_silent_errors ssi_silent_errors] 
e [#ssi_types ssi_types] 

e [#ssi_value_length ssi_value_length] 


ssi 
语法 :*ssi [ on | off ]* 
默认 值 :*ssi off* 


作用 域 :*http, server, location* 在 location 作 用 域 中 将 启用 SSI 文 件 义理 . 


ssi_silent_errors 
i&ik:*ssi silent errors [on|off]* 
EA &:*ssi silent errors off* 
作用 域 :*http, server, location* 


在 义理 SSI 文 件 出 错时 不 输出 错误 提示 :"[an error occurred while processing the directive] " 


ssi_types 

i&ik:"ssi types mime-type [mime-type ...]* 
EA f&:*ssi types text/html* 

作用 域 :*http, server, location* 


Enables SSI processing for MIME-types in addition to "text/html" types. 


ssi_value_length 
i&ik:*ssi value length length* 
EA &:*ssi value length 256* 
作用 域 :*http, server, location* 


定义 SSI 人 允许 使 用 的 参数 长 度 
SSI a 
格式 示例 如 下 : 


: <!--# command parameteri=value parameter2-value... --> 


支持 的 SSI 命令 如 下 : 


e block — command describes the block, which can be used as a silencer in command 
include . Inside the block there can be commands sst. 
e name — the name of the block. For example: 


:: the silencer: : 


* config — assigns some parameters with working SSI. 

e errmsg — the line, which is derived with the error during the SSI processing. By default, 
this string is used: "[an error occurred while processing the directive] " 

e timefmt — the time formatting string, as used in strftime(3). By default, this string is 
used: 


: "965A, %d-%b-%Y %H:%M:%S %Z" : To include time in seconds use the format "96s" as 


well. 


* echo - print a variable 
e var — the name of the variable 
e default - if the variable is empty, display this string. Defaults to "none". Example: 


:: </code> is the sameas  : no: 
e if / elif / else / endif — conditionally include text or other directives. Usage: 
dE Only one level of nesting is possible. 


e expr — the expression to evaluate. It can be a variable: ~~~ 


3j m] 


<!--# if expr="$name" --></code> A string comparison: <code><!--# if expr="$name = text" 


- «code»include — include a document from another source. 
- *file* — include a file, e.g. 








: <!--# include file-"footer.html" --> : 

- *virtual* — include a request, e.g. 

<!--# include virtual-"/remote/body.php?argument-value" -->Multiple requests will be issu 
- *stub* — The name of the block to use as a default if the request is empty or returns a 


<!--# block name="one" --» <!--# endblock --><!--# include virtual="/remote/body.php?argu 


- *wait* — when set to yes, the rest of the SSI will not be evaluated until the current r 





* set -assign a variable. 
e var — the variable. 
e value — its value. If it contains variable names, these will be evaluated. 


Net = 


ngx http ssi module $} AMA x BS: 


© $date local - 当前 的 本 地 时 区 时 间 . 配 置 选项 "timefmt" 控 制 格式 . 
e ddate_gmt - 当前 的 GMT 时 间 . 配置 选项 "timefmt" 控 制 格式 . 


参考 


Original Documentation 


HttpUserld 


The module ngx_http_userid_module gives out cookies for identification of clients. For 
logging it is possible to use variables $uid_got and $uid_set . Remark: keep in mind 
variables $uid_got and $uid_set are not accessible in SSI, because SSI filter module 


working before userid filter. 


This module is compatible with mod_uid for Apache. 


Example 
userid on; 
userid_name uid; 


userid_domain example.com; 


userid_path /i 

userid expires  365d; 

userid p3p 'policyrefz'"/w3c/p3p.xml", CP="CUR ADM OUR NOR STA NID"'; 
3% IR 4P 
userid 


syntax:*userid [on|v1 |log||off]* 

default:*userid off* 

context:*http, server, location* 

Enables or disables issuing cookies and logging requested cookies: 


e on - enables version 2 cookies and logs them; 

e v1 - enables version 1 cookies and logs them; 

* log - do not send cookies, but write down incoming cookies to log; 
e off - do not send cookies, and don't write them to logs; 


userid domain 


syntax:*userid domain [ name | none ]* 
default:*userid domain none* 
context:*http, server, location* 


Assigns the domain for cookie. The parameter "none" doesn't issue domain for cookie. 


userid_expires 
syntax:*userid_expires [ time | max ]* 
default:*none* 

context:*http, server, location* 

Sets the expiration time for the cookie. 


The parameter set & send-out browser expiration time for cookie. Value "max" assigns the 
time on 31 December, 2037, 23:55:55 gmt. This is the maximum time that older browsers 
understand. 


userid name 
syntax:*userid name name* 
default:*userid name uid* 


context:*http, server, location* 


Assigns name to cookie. 


userid_p3p 
syntax:*userid_p3p line* 
default:*none* 

context:*http, server, location* 


Directive assigns value for the header P3P, which will sent together with cookie. 


userid path 


syntax:*userid path path* 
default:*userid path /* 
context:*http, server, location* 


Sets the cookie path. 


userid_service 


syntax:*userid_service number* 


default:*userid_service address* 
context:*http, server, location” 


Directive assigns the IP address of the server which gave out cookie. If not set, version 1 
cookies set to zero, and for version 2 cookies the IP address of server. 


References 


Original Documentation 


BB Je b dob" SAY 


Additionz5" $ 


This module adds responses of other locations before and after the current location's 
response. 


It is implemented as an output filter, the contents of the main request and subrequests to 
other locations are not buffered completely and are still sent to the client in a streaming 
fashion. Because the length of the final response body is unkown while sending the HTTP 
headers, the HTTP chunked encoding is always used here. 


Installation 
By default the module is not built, it is necessary to enable its build with 


./configure --with-http addition module 


at compilation time. 


Example: 


location / { 
add_before_body /before_action; 
add_after_body /after_action; 


Limitations 


Note that as of 0.8.17 no contents will be added if the current location is served as a 
subrequest itself. Consider the following example: 


location /foo { 
add_before_body /bar; 
} 


location /bar { 
add_before_body /baz; 
} 


Then accessing /foo won't get /baz inserted before the contents of the subrequest /bar. 


Also note that at this time, only strings can be used in before/after body locations, not 
variables. So 


location / { 
set $before_action /before_action; 
add_before_body $before_action; 


} 


will not work as expected (although the configuration file will still load properly). 
Directives 


add_before_body 


syntax:*add_before_body uri* 
default:*no* 
context:*http, server, location* 


Directive adds content of uri before the response body, issued as a result of the work of the 
assigned subrequest. 


add_after_body 


syntax:*add_after_body uri* 
default:*no* 
context:*http, server, location” 


Directive adds content of uri after the response body, issued as a result of the work of the 
assigned subrequest. 


addition_types 
syntax:*addition_types mime-type [mime-type ...]* 
default:*text/html* 


context:*http, server, location* 


Directive (since 0.7.9) allows you to add text only to locations of the specified MIME-types 
(defaults to "text/html"). 


(Before 0.8.17, this directive was mispelled as "addtion types" in the source. This bug has 
been fixed in 0.8.17.) 


References 
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EmbeddedPerl 


This module makes it possible to execute Perl directly within Nginx and call Perl via SSI. 


Building Module at Compile-time 


Unless built at compile-time, the module is not available. The default is to not build this 
module. If you want to enable this module, is necessary to specify --with-http_perl_module 
when running configure. 


Your system must have Perl 5.6.1 or above. 


Known Problems 


This module is experimental; therefore anything is possible and bugs are likely. 


1. If a Perl module performs protracted operation, (for example DNS lookups, database 
queries, etc), then the worker process that is running the Perl script is completely tied 
up for the duration of script. Therefore embedded Perl scripts should be extremely 
careful to limit themselves to short, predictable operations. 

2. It's possible for Nginx to leak memory if you reload the configuration file (via ‘kill -HUP '). 


Example: 


http { 


perl modules  perl/lib; 
perl require hello.pm; 


perl set $msie6 ' 
sub { 
my $r - shift; 
my $ua = $r-»-header in("User-Agent"); 


return "" if $ua -- /Opera/; 
return "1" if $ua =~ / MSIE [6-9] \.\d+/; 
return ""; 

3 

server { 


location / { 
perl hello: :handler; 
H 
} 


perl/lib/hello.pm: 


package hello; 
use nginx; 


sub handler { 
my $r = shift; 
$r->send_http_header ("text/html"); 
return OK if $r->header_only; 


$r->print("hello!\n<br/>"); 
$r->rflush; 


if (-f $r->filename or -d ) { 


$r->print($r->uri, " exists!\n"); 


return OK; 


perl 

syntax:*perl module::function | 'sub (...)* 
default:*no* 

context:*location* 


Directive establishes a function for the data location. 


perl modules 


syntax:*perl modules path* 
default:*no* 
context:*http* 


Directive assigns additional path for Perl modules. Since version 0.6.7 this path is relative to 
directory of nginx configuration file nginx.conf, but not to nginx prefix directory. 


perl require 
syntax:*perl require module* 


default:*no* 


context:*http* 


There can be multiple perl require directives. 


perl set 


syntax:*perl set module::function | 'sub {...}'* 
default:*no* 
context:*http* 


Directive establishes the function of variable ??? 


Calling Perl from SSI 
Instruction format is as follows: 


<!- # perl sub="module::function" arg="parameteri" arg="parameter2"... > 


Methods of request object $r: 


e $r->args - method returns the arguments of request. 

e $r->filename - method returns the name of file, which corresponds to URI request. 

e $r->has_request_body(function) - method returns 0, if there is no request body. But if 
the request body exists, then the passed function is established and 1 returned. At the 
end of the body processing, nginx will call the established processor. Example usage: 


package hello; 


use nginx; 


sub handler { 


} 


my $r = shift; 
if ($r->request_method ne "POST") { 


return DECLINED; 
} 


if ($r->has_request_body(hello::post)) { 


return OK; 


} 


return 400; 


sub post { 


my $r = shift; 

$r->send_http_header; 

$r->print("request_body: \"", $r->request_body, "\"<br/>"); 
$r->print("request_body_file: \"", $r->request_body_file, "\"<br/>\n"); 
return OK; 


. END . 


$r->header_in(header) - retrieve an HTTP request header. 

$r-^header only - true if we only need to return a response header. 
$r->header_out(header, value) - set a response header. 

$r->internal_redirect(uri) - method makes internal redirect to the indicated uri. Redirect 
occurs only after the completion of Perl script. 

$r->print(args, ...) - sends data to client. 

$r-^request body - method returns the request body of client when the body is not 
recorded into the temporary file. 


So that the body of the demand of client is guaranteed to remain in memory, it is necessary 


to limit its size with the aidof client max body. size and to assign sufficient size for the buffer 


using client body buffer size. 


$r-^request body file — method returns the name of the file, in which is stored the 
body of the demand of client. The file must be removed on the completion of work. So 
that the body of the request would always be written to the file, it is necessary to 
indicate client body in file only on. 

$r-»request method — method returns the HTTP method of the request. 
$r->remote_addr - method returns IP address of client. 

$r->rflush - method immediately transmits data to client. 

$r->sendfile(file [, displacement [, length ] ) - transfers to client contents of the file 


indicated. The optional parameters indicate initial offset and length of transmitted data. 
Strictly the transmission of data occurs only after the completion of the perl script. 

e $r->send_http_header(type) - adds header to response. The optional parameter "type" 
establishes the value of line "Content-Type" in the title of answer. 

e $r->unescape(text) - decodes the text, assigned in the form 96XX. 

e $r->uri - returns request URI. 


References 


Original Documentation 


flv 


This module provides the ability to seek within FLV (Flash) files using time-based offsets. 
本 模块 提供 FLV 文 件 加 载 基于 时 间 位 移 . 

Module ngx http flv module offers special handling of files it handles: 

模块 ngx_http_flv_module 提 供 特 殊 义 理 的 文件 , 它 义理 : 


e adds FLV header to the requested file; 

。 添加 FLV 头 请 求 的 文件 ; 

e transfers file, beginning from the displacement, specified in the request argument 
start=XXX. 

。 传输 文件 ， 从 开始 的 位 移 ， 在 请 求 参数 中 指定 start=XXX. 


This module is not compiled by default and must be specified using the --with- 
http flv module argument to configure when compiling Nginx. 


本 模块 必需 在 编译 nginx 时 加 上 --with-http_flv_module. 
例如 : 


location ~ \.flv$ { 


flv; 
} 


HttpGzipStatic 


Before serving a file from disk to a gzip-enabled client, this module will look for a 
precompressed file in the same location that ends in ".gz". The purpose is to avoid 
compressing the same file each time it is requested. 


在 开始 压缩 创建 硬盘 上 的 文件 之 前 ， 本 模块 将 查找 同 目录 下 同名 的 .gz 压缩 文件 ， 以 避免 同一 
文件 再 次 压缩 。 


ngx http gzip static module was introduced in nginx 0.6.24. You must enable support at 
compile time: 


nginx 0.6.247F 3870] Angx http gzip static module . 编译 时 加 上 : 


./configure --with-http gzip static module 


例如 : 


gzip static on; 


gzip http version alaale 


gzip_proxied expired no-cache no-store private auth; 
gzip_disable "MSIE [1-6]\."; 
gzip_vary on; 
HS 
AT 


gzip_static 
syntax:*gzip_static on|off* 
default:*gzip static off* 
context:*http, server, location* 


Enables the module. You should ensure that the timestamps of the compressed and 
uncompressed files match. 


启动 模块 。 您 应 该 确保 压缩 和 解压 文件 的 时 间 戳 匹配 。 


gzip_http_version 


See NginxHttpGzipModule 


gzip_proxied 


See NginxHttpGzipModule 


gzip_disable 


See NginxHttpGzipModule 


gzip_vary 


See NginxHttpGzipModule 


Randomlndex 

Pick a random directory index from a directory. 
从 目录 中 选择 一 个 随机 目录 索引 。 

例如 : 


location / { 


random_index on; 


} 


HttpGeolP 


This module creates ngx http geoip module variables based on the IP-address of the client 
matched against the MaxMind GeolP binary files. This module appeared in nginx version 
0.8.6. 


本 模块 ngx_http_geoip_module 的 变量 基于 IP 地 址 匹配 MaxMind GeolP 二 进 制 文件 . 这 个 模块 
开始 出 现在 nginx0.8.6。 


Precondition 首先 
This module needs the geo databases and the library to read the database. 


模块 必需 有 geo 数 据 库 和 读 取 数据 库 类 


# 下 载 免费 的 geo_city 数 据 库 

wget http://geolite.maxmind.com/download/geoip/database/GeoLiteCity.dat.gz 

# 下 载 免费 的 geo_coundty 数 据 库 

wget http://geolite.maxmind.com/download/geoip/database/GeoLiteCountry/GeoIP.dat.gz 
# 在 debian 中 安装 libgeoip: 

sudo apt-get install libgeoip-dev 

# 其 它 系 统 ， 你 可 以 下 载 并 编译 一 个 源 文件 

wget http://geolite.maxmind.com/download/geoip/api/c/GeolIP. tar.gz 


在 centos 可 以 用 yum 安 装 : 


yum install geoip 
编译 
./configure --with-http_geoip_module 


例如 


http { 
geoip country  GeoIP.dat; 
geoip city GeoLiteCity.dat; 


TET 


geoip country 


syntax:*geoip country path/to/db.dat;* 


default: none 


context:*http* 


The directive indicates the path to the .dat file used for determining the visitor's country from 
the IP-address of the client. When set the module makes available the following variables: 


dat 文 件 用 于 判断 访问 者 IP 中 的 国家 。 当 前 模块 下 可 用 的 变量 : 


e $geoip country code; -国家 名 的 前 两 个 字母 , 如 , "RU", "US". 
e $geoip_country_code3; - 国家 名 的 前 三 个 字母 , 如 , "RUS", "USA". 
e $geoip country name; -国家 名 称 , 如 , "Russian Federation", "United States". 


If you only need the country's name, you can just set the geoip_country database(1.1M), 
while the geoip_city database is much bigger(43M) and all the databses will be cached in 
memory. 


如 果 你 只 需要 国家 ， 你 只 需 设 置 geoip_country 数 据 库 (1.1M), 但 城市 的 ip 数据 库 就 比较 大 
(43M) 并 且 将 加 载 到 内 存 当 缓存 。 


geoip_city 
syntax:*geoip_city path/to/db.dat;* 
default: none 


context:*http* 


The directive indicates the path to the .dat file used for determining countries, regions and 
cities from IP-address of the client. When set the module makes available the following 
variables: 


dat 文 件 用 于 判断 访问 者 IP 中 的 国家 、 省 ， 城 市 。 当 前 模块 下 可 用 的 变量 : 


e $geoip_city_country_code; -国家 名 的 前 两 个 字母 , SD, "RU", "US". 

e $geoip_city_country_code3; - 国家 名 的 前 三 个 字母 , 如 , "RUS", "USA". 

e $geoip_city_country_name; -国家 名 称 , 40, "Russian Federation", "United States". 

e $geoip region; - 省 ， 州 或 区 名 (province, region, state, province, federal land, and the 
like), 40, "Moscow City", "DC". 

e $geoip_city; - 城市 名 称 , 40, "Moscow", "Washington". 

e $geoip postal code; - 邮政 编号 . 
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HttpReallp 


This module lets to change the client's IP address to value from request header (e. g. 


X-Real-IP Of X-Forwarded-For ). 


It is useful if nginx works behind some proxy of L7 load balanver, and request come from 
local IP, but proxy add request header with client's IP. 


This module isn't built by default, enable it with the configure option 


--with-http realip module 


User Note: "You will build a list of trusted proxies (see below) and the first IP in the header 
which is not trusted will be used as the client IP." Source: README of the Apache module 
mod extract . Quite informative, about why and how this security feature is helpful. 


Example: 


set real ip from 192.168.1.0/24; 
set real ip from 192.168.2.1; 
real ip header X-Real-IP; 


3%, IN 4P 


set real ip from 


* 


syntax:*set real ip from [the address|CIDR] 
default: none 
context:*http, server, location* 


This directive describes the trusted addresses, which transfer accurate address for the 
replacement. 


real ip header 
syntax:*real ip header [X-Real-IP|X-Forwarded-For]* 
default:*real ip header X-Real-IP* 


context:*http, server, location* 


This directive sets the name of the header used for transferring the replacement IP address. 
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HttpSSL 


This module enables HTTPS support. 
It supports checking client certificates with two limitations: 


e it is not possible to assign the list of the abolished certificates (revocation lists) 

e if you have a chain certificate file (sometimes called an intermediate certificate) you 
don't specify it separately like you do in Apache. Instead you need to add the 
information from the chain cert to the end of your main certificate file. This can be done 
by typing "cat chain.crt >> mysite.com.crt" on the command line. Once that is done you 
won't use the chain cert file for anything else, you just point Nginx to the main certificate 
file. 


By default the module is not built, it is necessary to specify that it be built with with the --with- 
http ss! module parameter to ./configure. Building this module requires the OpenSSL 
libraries and include-files, often are the necessary files in separate packages. 


The following is an example configuration, to reduce the CPU load it is recommended to run 
one worker process only and to enable keep-alive connections: 


worker processes 1; 


http { 
server { 
listen 443; 
ssl on; 
ssl certificate /usr/local/nginx/conf/cert.pem; 
ssl certificate key  /usr/local/nginx/conf/cert.key; 
keepalive timeout 70; 
} 
} 


When using chain certificates, just append the extra certificates into your .crt file (cert.pem in 
the example). Your own certificate needs to be on top of the file, otherwise key get a 
mismatch with the key. 


Generate Certificates 
To generate dummy certficates you can do this steps: 


cd /usr/local/nginx/conf 

openssl genrsa -des3 -out server.key 1024 

openssl req -new -key server.key -out server.csr 

cp server.key server.key.org 

openssl rsa -in server.key.org -out server.key 

openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt 


€» € € 0 0 € 


Configure the new certificate into nginx.conf: 


server { 


server_name YOUR_DOMAINNAME_HERE; 

listen 443; 

ssl on; 

ssl_certificate /usr/local/nginx/conf/server.crt; 

ssl certificate key /usr/local/nginx/conf/server.key; 


Restart Nginx. 


Now all ready to access using: 


https://YOUR DOMAINNAME HERE 


$ IR 4P 


ssl 

syntax:*ssl [on|off]* 
default:*ssl off* 
context:*main, server* 


Enables HTTPS for a server. 


ssl certificate 


syntax:*ssl certificate file* 
default:*ss| certificate cert.pem* 
context:*main, server* 


Indicates file with the certificate in PEM format for this virtual server. The same file can 
contain other certificates, and also secret key in PEM format. Since version 0.6.7 the file 
path is relative to directory of nginx configuration file nginx.conf, but not to nginx prefix 
directory. 


ssl certificate key 
syntax:*ssl| certificate key file* 


default:*ss| certificate key cert.pem* 


context:*main, server* 


Indicates file with the secret key in PEM format for this virtual server. Since version 0.6.7 the 
filename path is relative to directory of nginx configuration file nginx.conf, but not to nginx 
prefix directory. 


ssl client certificate 


syntax:"ssl client certificate file* 
default:*none* 
context:*main, server* 


Indicates file with certificates CA in PEM format, utilized for checking the client certificates. 


ssl dhparam 

syntax:*ss| dhparam file* 

default:*none* 

context:*main, server* 

Indicates file with Diffie-Hellman parameters in PEM format, utilized for negotiating TLS 


session keys. 


ssl ciphers 


syntax:*ssl_ciphers file* 
default:*ss| ciphers ALL:!:ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP* 
context:*main, server* 


Directive describes the permitted ciphers. Ciphers are assigned in the formats supported by 
OpenSSL, for example: 


Ssl ciphersALL: ADH: !EXPORT56:RC4+RSA: *HIGH: +MEDIUM: +LOW: *SSLv2: *EXP ; 


Complete list can be looked with the following command: 


openssl ciphers 


ssl crl 


syntax:*ssl crl file* 
default:*none* 
context:*http, server* 


This directive (0.8.7+) specifies a file with the revoked certificates (CRL) in the PEM, which 
is used to check for client certificates. 


ssl prefer server ciphers 


syntax:*ss| prefer server ciphers [on|off]* 
default:*ss| prefer server ciphers off* 
context:*main, server* 


Requires protocols SSLv3 and TLSv1 server ciphers be preferred over the client's ciphers. 


ss| protocols 


syntax:*ssl_ protocols [SSLv2] [SSLv3] [TLSv1]* 
default:*ss! protocols SSLv2 SSLv3 TLSv1* 
context:*main, server* 


Directive enables the protocols indicated. 


ss| verify client 


syntax:*ss| verify client on|offjask* 
default:*ss! verify client off* 
context:*main, server* 


Directive enables verifying client certificates. Parameter 'ask' checks a client certificate if it 
was offered. 


ssl verify depth 
syntax:*ss| verify depth number* 


default:*ss! verify depth 1* 


context:*main, server* 


Sets depth checking in the chain of client certificates. 


ss| session cache 


syntax:*"ss| session cache off|none|builtin:size and/or shared:name:size* 
default:*ss| session cache off* 
context:*main, server* 


The directive sets the types and sizes of caches to store the SSL sessions. 
The cache types are: 


e off -- Hard off: nginx says explicitly to a client that sessions can not reused. 

e none -- Soft off: nginx says to a client that session can be resued, but nginx actually 
never reuses them. This is workaround for some mail clients as ssl! session cache may 
be used in mail proxy as well as in HTTP server. 

e builtin -- the OpenSSL builtin cache, is used inside one worker process only. The cache 
size is assigned in the number of the sessions. Note: there appears to be a memory 
fragmentation issue using this method, please take that into consideration when using 
this. See "References" below. 

e shared -- the cache is shared between all worker processes. The size of cache is 
assigned in the bytes, 1 MB cache can contain about 4000 sessions. Each shared 
cache must have arbitrary name. Cache with the same name can be used in several 
virtual servers. 


It is possible to use both types of cache simultaneously, for example: 


ssl session cache builtin:1000 shared:SSL:10m; 
However, the only shared cache usage without that builtin should be more effective. 


ss| session timeout 


syntax:*ss| session timeout time* 
default:*ss| session timeout 5m* 
context:*main, server* 


Assigns the time during which the client can repeatedly use the parameters of the session, 
which is stored in the cache. 


This module supports several nonstandard error codes which can be used for debugging 
with the aid of directive error_page: 


e 495 - error checking client certificate 
e 496 - client did not grant the required certificate 
e 497 - normal request was sent to HTTPS 


Debugging is done after the request is completely dismantled and are accessible via 
variables such as $request_uri, Suri, $arg and others. Built-in variables Module 
ngx_http_ssl_module supports several built-in variables: 


e $ssl_cipher returns the line of those utilized it is cipher for established SSL-connection 

e $ssl_client_serial returns the series number of client certificate for established SSL- 
connection 

e $ssl client s dn returns line subject DN of client certificate for established SSL- 
connection 

e $ssl client i dn returns line issuer DN of client certificate for established SSL- 
connection 

e $ssl protocol returns the protocol of established SSL-connection 


ssl engine 
syntax:*ss| engine* 


This allows specifying the OpenSSL engine to use, like Padlock for example. It requires a 
more recent version of OpenSSL. 
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StubStatus 模 块 
这 个 模块 能 够 获取 Nginx 自 上 次 启动 以 来 的 工作 状态 
此 模块 非 核心 模块 ， 需 要 在 编译 的 时 候 手 动 添 加 编译 参数 --with-http_stub_status_module 


配置 说 明 


DIETE UI /nginx status { 

: # copied from http://blog.kovyrin.net/2006/04/29/monitoring-nginx-with-rrdtool/ 
: stub status on; 

: access log off; 

: allow SOME.IP.ADD.RESS; 

deny all; 


BA 
AT 


e [#stub_status stub status] 


stub status 


i&ik:*stub status* on 

默认 值 :*None* 

VE FA is :*location* 

创建 一 个 location 区 域 启 用 stub. status 


"stub status" 模块 返回 的 状态 信息 跟 mathopd's 的 状态 信息 很 相似 . 返回 的 状态 信息 如 下 : 


Active connections: 291 

server accepts handled requests 

: 16630948 16630948 31070465 
Reading: 6 Writing: 179 Waiting: 106 


active connections -- 对 后 端 发 起 的 活动 连接 数 


server accepts handled requests -- nginx 总 共处 理 了 16630948 个 连接 , 成 功 创建 
16630948 次 握手 (证 明 中 间 没 有 失败 的 ), 总 共处 理 了 31070465 个 请 求 (平均 每 次 握手 处 理 了 
1.8 个 数据 请 求 ) 


reading -- nginx 读 取 到 客户 端的 Header 信 息 数 


writing -- nginx 返回 给 客户 端的 Header 信 息 数 


waiting -- F keep-alive 的 情况 下 ， 这 个 值 等 于 active - (reading + writing) ， 
是 Nginx 说 已 经 处 理 完 正 在 等 候 下 一 次 请 求 指令 的 驻 留连 接 


Examples 


http://blog.kovyrin.net/2006/04/29/monitoring-nginx-with-rrdtool/ 
http://dev.2xlp.com/svn/nginxconfig/trunk/cont/rrd/__README.txt 


HttpSubstitution 
This module can search and replace text in the nginx response. It is only available if the 


--with-http_sub_module option 


was specified for ./configure. 


本 模块 可 以 在 nginx 的 回应 中 查找 和 替换 文本 .在 编译 nginx 时 必需 加 上 --with-http_sub_module 
option 


例如 : 


location / { 
sub_filter </head> 
"</head><script language="javascript" src="$script"></script>'; 
sub_filter_once on; 


sub filter 


syntax:"sub filter text substitution* 
default:*none* 
context:*http, server, location* 


sub filter allows replacing some text in the nginx response with some other text, 
independently of the source of the data. The matching is case-insensitive. Substitution text 
may contain variables. Only one substitution rule per location is supported. 


sub filter 允许 蔡 换 源 文 件 里 的 多 个 文本 (多 次 蔡 换 ) 匹配 是 非常 快速 的 。 蔡 换 必 须 包含 变 


量 ， 一 个 location 只 能 一 个 替换 规则 . 


sub filter once 
syntax:*sub filter once onloff* 
default:*sub filter once on* 


context:*http, server, location* 


sub_filter_once off allows to search and replace all matching lines, the default is replacing 
only the first one. 


sub filter once off Riya REA T, SUARSHRSS— T. 


sub filter types 

syntax:*sub filter types mime-type [mime-type ...]* 
default:*sub filter types text/html* 

context:*http, server, location* 


sub filter types is used to specify which content types should be checked for sub filter. The 
default is only text/html. 


sub_filter_types 用 于 指定 替换 sub_filter 的 类 型 ， 默 认为 text/html. 
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HttpDav 模 块 
这 个 模块 可 以 为 Http webDAV 增加 PUT, DELETE, MKCOL, COPY 和 MOVE 等 方法 。 


这 个 模块 在 默认 编译 的 情况 下 不 是 被 包含 的 ， 你 需要 在 编译 时 指定 如 下 参数 : 


./configure --with-http_dav_module 


配置 范例 : 


location / { 
root /data/www; 
client_body_temp_path /data/client_temp; 


dav_methods PUT DELETE MKCOL COPY MOVE; 


create_full_put_path on; 
dav_access group:rw all:r; 


limit except GET { 
allow 192.168.1.0/32; 


deny all; 
} 
} 
配置 指导 
dav_access 


syntax: dav_access user:permissions [users:permissions] ... 
default: dav_access user:rw 
context: http, server, location 


这 个 指令 是 赋予 某 个 目录 或 文件 以 访问 权 ， 如 : 


dav access user:rw group:rw all:r; 


如 果 给 一 个 用 户 组 或 所 有 用 户 任 何 权 限 ，user 这 个 参数 就 没有 必要 设置 了 ， 如 : 


dav access group:rw all:r; 


dav methods 


syntax: dav methods [off|put|delete|mkcol|copy|move] ... 


default: dav methods off 


context: http, server, location 


这 个 指令 用 于 于 指定 HTTP 和 WebDAV 的 方法 ， 设 置 它 为 off 时 其 所 有 的 方法 都 将 无 效 (忽视 你 已 经 设置 的 方法 ) 。 





Put 方法 的 目标 文件 必须 是 和 Nginx 的 临时 文件 夹 client_body_temp_path 在 同一 个 分 区 里 。 
当 使 用 Put 方法 创建 一 个 文件 时 ， 有 可 能 会 通过 设 定 date header 修改 文件 创建 日 期 。 


create full put path 


syntax: create full put path on|off 
default: create full put path off 


context: http, server, location 





默认 情况 下 ，Put 方法 只 能 在 已 存在 的 目录 里 创建 文件 。 当 然 了 Nginx 必须 得 有 这 个 目录 的 修改 和 写 入 权限 。 


GooglePerftools 


This module enables Google Performance Tools profiling for workers. This module appeared 
in nginx version 0.6.29. 


By default the module is not built, it is necessary to enable its build with 


./configure --with-google_perftools_module 
at compilation time. 


Example 


google_perftools_profiles /path/to/profile; 
Profiles will be stored as /path/to/profile. 


3% ER 4P 


google perftools profiles 


syntax:*google perftools profiles path* 
default:*none* 


Directive specifies the base filename of profiles collected by Google Perftools profiler. The 
workers PIDs will be appended to the specified base filename. 


HttpXSLT 


This module is a filter which converts an XML response with the aid of one or more XSLT 
templates. 


This module was introduced in 0.7.8 and needs to be enabled via 


./configure --with-http_xslt_module 


Example: 


location / { 


xml_entities /site/dtd/entities.dtd; 
xslt_stylesheet /site/xslt/one.xslt param=value; 
xslt_stylesheet /site/xslt/two.xslt; 
} 
HS 
AT 


xslt entities 


syntax:*xml entities * 
default:*no* 
context:*http, server, location* 


Specifies the DTD file which describes symbolic elements (xml entities). This file is compiled 
at the stage of configuration. For technical reasons it's not possible to specify entities in the 
XML being processed, therefore they are ignored, but this specially assigned file is used 
instead. In this file it is not necessary to describe structure of processed XML , it is sufficient 
only to declare necessary symbolic elements, for example: 


<! ENTITY of nbsp " “> 


xslt stylesheet 


syntax:*xslt stylesheet template [parameter[[ parameter... /] default:no* 
context:*http, server, location* 


Specifies the XSLT template with its parameters. Template is compiled at the stage of 
configuration. The parameters are assigned as shown: 


param=value 


You can specify parameters either one per line, or separate multiple parameters with colon 
(“: ”) If the parameter itself contains the character “:”, escape it as "963A". Furthermore, libxslt 
requires that string parameters should be quoted by the single or dual quotation marks if 
they contain non-alphanumeric characters, for example: 


parami-'http963A//www.example.com': param2-value2 


It's possible to use variables as parameters, for example, the entire line of the parameters 
can be substituted with one variable: 


location / { 
xslt_stylesheet /site/xslt/one.xslt 
$arg xslt params 


parami-'$valuei1': param2-value2 
param3-value3; 


It is possible to specify several templates, in which case they would be chained together in 
the order of their declaration. 


xslt types 

syntax:*xslt types mime-type [mime-type...]* 
default:*xslt types text/xml* 

context:*http, server, location* 


Permit processing responses with specified MIME-types in addition to “text/xml”. If XSLT 
output mode is HTML, then the response MIME-type changes to "text/HTML ". 


HttpSecureLink 


This module computes and checks request URLs for a required security token. This module 
is not compiled by default and must be specified using the 

这 个 模块 计算 和 检测 URL 请 求 中 必须 的 安全 标识 

这 个 模块 没有 默认 编译 ， 在 编译 Nginx 时 ， 必 须 使 用 明确 的 配置 参数 


--with-http_secure_link_module 


argument to configure when compiling Nginx. Note that this module is only supported in 
nginx version 0.7.18 and higher. 
来 说 明 配 置 .这 个 模块 在 Nginx 0.7.18 及 以 上 版 本 中 被 支持 . 


Example usage: 


location /prefix/ { 
secure_link_secret secret_word; 


if ($secure link = "") { 
return 403; 
} 


BA 

A TI 
syntax:*secure_link_secret secret_word* 
default:*none* 


context:*location* 


The directive specifies a secret word to verify requests. The full URL for a protected links 
follows this form: 
这 个 指令 明确 一 个 安全 关键 字 来 审核 请 求 。 完 整 的 被 保护 的 URL 如 下 表 : 


/prefix/hash/reference 


hash is computed as as f&iFdmd5( BE Ze 4 us sa e Ait Be 


md5 (reference, secret word); 


prefix is the scope of the location block, and must not be /. secure_link can only be used in 


non-root paths. 
前 级 是 定位 块 的 范围 ， 绝 对 不 能 使 用 /。 安 全 连接 只 能 被 用 在 非 根 目录 路 径 。 


变量 


$secure_link 


Automatically set to the reference component of the URL, isolated from the prefix and hash. 
If the hash is incorrect, an empty string is returned instead. 
自动 设置 模块 到 URL 的 关联 ,分 开 前 级 和 HASH。 如 果 HASH 不 正确 ， 将 返回 空 字符 串 。 


HttplmageFilter 


Version: 0.7.54+ 


This module is a filter for transforming JPEG, GIF and PNG images. It is not enabled by 
default to enable it, provide this option to ./configure when building nginx: 

这 个 模块 用 来 分 发 JPEG，GIF 和 和 PNG 图片。 这 个 没有 默认 开店， 在 编译 nginx 中 通 

过 ./configure 参 数 配置 


--with-http_image_filter_module 





libgd is required to build and run the module. We recommend using the latest version of 
libgd. 
编译 和 运行 这 个 模块 必须 安装 libgd 库 。 我 们 推荐 使 用 最 新 版 本 的 Libgd. 


Example Configuration 


location /img/ { 


proxy_pass http://backend; 
image_filter resize 150 100; 
error_page 415 = /empty; 

} 

location = /empty { 
empty_gif; 

HS 
H TD 


image filter 

Syntax:*image filter (test|size|resize width height|crop width height)* 
Default:*none* 

Context:*location* 


Specifies the type of transformation to apply to the image, one of the below: 
详细 的 图 片 后 级 类 型 如 下 : 


e test: checking that the response is indeed an image format JPEG, GIF or PNG. 
Otherwise, an error 415. 
测试 : 测试 确定 图 片 文件 的 后 级 格式 为 JPEG，GIF OR PNG。 人 否则 返回 415 错 误 


e size: Gives information about the image in JSON format. For example, 
尺寸 : 返回 JSON 格 式 的 图 片 信 息 。 例 如 : 


{ "img" : { "width": 100, "height": 190, "type": "gif" } } 
Or if an error occurs, 
或 者 如 果 发 生 错 误 ， 

{} 

e resize: proportionally reduces the image to a specified size. 

调整 大 小 : 缩 略图 片 到 特定 的 尺寸 
e crop: proportionally reduces the image to a specified size and trims extra edge. 
切割 : 切割 图 片 到 特定 的 尺寸 和 特定 的 分 辩 率 

image_filter_buffer 
Syntax:*image filter buffer size* 
Default:*1M* 
Context:*http, server, location” 
Sets the maximum size for reading the image. 
设置 读 取 文件 的 最 大 的 尺寸 
image filter jpeg quality 
Syntax:*image filter jpeg quality [0...100]* 
Default:*75* 
Context:*http, server, location” 
Sets the rate of loss of information when processing the images as JPEG. The maximum 
recommended value is 95. 
设置 处 理 JPEG 图 片 的 丢失 信息 率 .推荐 的 最 大 值 为 95 
image_filter_transparency 
Syntax:*image filter transparency on|off* 


Default:*on* 


Context:*http, server, location” 


This directive allows you to disable image transparency in GIF and palette-based PNG to 
improve image resampling quality. 
这 个 指令 容许 你 关闭 GIF 图 片 的 透明 度 和 PNG 图 片 质量 


True color PNG alpha-channels are always preserved despite this setting. 
真 彩色 PNG 图 片 保存 忽略 设 定 


Note: Grayscale PNG's are untested, but should be handled as truecolor PNGs. 
注释 : 不 度 PNG 图 片 未 被 设置 ， 但 应 该 被 作为 真 彩色 PNG 图 片 处 理 
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mailke" 


MailCore 


Nginx is able to handle and proxy the following mail protocols: 
Nginx 能 够 处 理 和 代理 以 下 邮件 协议 : 


e IMAP 
e POP3 
e SMTP 


认证 


nginx uses external HTTP-like server to learn which IMAP/POP backend it should connect 
to. 


nginx 的 IMAP POP 后 端 处 理 类 似 HTTP 服 务 器 的 连接 方式 。 


nginx passes authorization information in HTTP headers: 
nginx 在 HTTP 头 里 传递 授权 信息 : 


GET /auth HTTP/1.0 

Host: auth.server.hostname 
Auth-Method: plain 
Auth-User: user 

Auth-Pass: password 
Auth-Protocol: imap 
Auth-Login-Attempt: 1 
Client-IP: 192.168.1.1 


The good response is: 
正常 的 回应 是 : 


HTTP/1.0 200 OK 4 this line is actually ignored and may not exist at all íT TRER 


Auth-Status: OK 
Auth-Server: 192.168.1.10 
Auth-Port: 110 


Auth-User: newname # you may override the user name to login to a backend 你 可 以 重 写 用 户 : 


属于 


When authenticating with APOP for POP3, you must return Auth-Pass as well: 
当 在 POP3 中 使 用 APOP 协 议 时 ， 你 必须 返回 验证 密码 如 下 : 


HTTP/1.0 200 OK # this line is actually ignored and may not exist at all 
Auth-Status: OK 

Auth-Server: 192.168.1.10 

Auth-Port: 110 

Auth-User: newname # you may override the user name to login to a backend 





Auth-Pass: password # this must be the user's password in cleartext 这 里 必须 是 明文 形式 的 用 户 


El — | 








The failed response is: 


失败 的 回应 是 : 
HTTP/1.0 200 OK # this line is actually ignored and may not exist at all 
Auth-Status: Invalid login or password 
Auth-Wait: 3 # nginx will wait 3 seconds before reading Nginx 在 读 之 前 等 待 3 秒 


# client's login/passwd again 


auth 


Renamed to pop3_auth in 0.5.15 


imap_capabilities 

syntax:*imap capabilities*"capability1" ["capability2" .. "capabilityN"] 
default:*"IMAP4" "IMAP4rev1" "UIDPLUS"* 

context:*main, server* 


With this directive you can set the list of IMAP protocol extensions presented to the client 
upon issuing the IMAP command CAPABILITY. STARTTLS is automatically added if you 
enable the starttls directive. 

使 用 这 条 指令 你 可 以 设置 IMAP 协 议 列表 来 扩展 现 有 的 客户 端 上 的 IMAP 的 命 人 CAPABILITY。 
如 果 你 启用 了 STARTTLS 那 么 STARTTLS 命 邻 将 自动 加 入 。 


The current list of standardized IMAP expansions is published on www.iana.org. 
现在 所 列 出 的 标准 的 IMAP 扩 展 发 布 在 www.iana.org 上 。 


mail { 
imap_capabilities NAMESPACE SORT QUOTA; 
} 


Will the defaults be also set, | haven't see this in the source?! (al 2007-05-11) 
这 个 设置 了 默认 了 ?我 在 源码 中 没有 看 到 ! 
imap client buffer 


syntax:*imap client buffer size* 
default:*4K/8K* 


context:*main, server* 


With this directive you can set the read buffer for IMAP commands. The default value is 
equal to the size of a page (this can be either 4K or 8K depending on the platform). 


listen 


syntax:*listen*address:port [ bind ] 
default:*no* 
context:*server* 


The directive specifies the address and port, on which the server accepts requests. It is 
possible to specify address or port only, besides, an address can be the server name, for 
example: 

当 服务 器 接收 请 求 时 ， 这 条 指令 指定 地 址 和 端口 。 这 个 可 能 只 知道 地 址 或 者 端口 ， 另 外 ， 地 
址 可 能 是 服务 器 名 ， 例 如 : 


listen 127.0.0.1:8000; 
listen 127.0.0.1; 


listen 8000; 


listen *:8000; 
listen localhost:8000; 


IPv6 address(>=0.7.58) are set in square brackets: 


listen [::]:8000; 
listen [fe80::1]; 


In directive listen it is possible to indicate the system call bind(2). 
listen 指 今 可 能 显示 显示 系统 命令 bind. 


bind -- indicates that it is necessary to make bind(2) separately for this pair of address:port. 
If several directives listen with identical port but with different addresses and one of the 
directives listen to all addresses for this port (:port) then Nginx will make bind(2) only to :port. 
In this case the address is determined by the system call getsockname(). 

bind -- bind 指 使 必须 是 绑 定 一 对 地 址 : 端口 。 如 果 多 个 指 倒 监听 不 同 地 址 的 相同 的 端口 ， 另 
一 个 指令 监听 所 有 地 址 的 端口 (: 端 口号 )， 这 样 的 话 Nginx 将 指 执行 bind 的 :端口 号 .这 样 的 话 地 
址 只 能 是 系统 命令 getsockname() 的 值 。 


pop3_auth 
syntax:*pop3_auth*/plain] [apop] [cram-md5] 


default:*plain* 


context:*main, server* 


With this directive you can set the permitted methods of authentication for POP3 clients: 
使 用 这 条 指令 你 可 以 设置 验证 POP3 客 户 端的 验证 方法 : 


e plain - USER/PASS , AUTH PLAIN , AUTH LOGIN 
e apop - APOP 
e cram-md5 - AUTH CRAM-MD5 
pop3 capabilities 
syntax:*pop3 capabilities*"capability1" ["capability2" .. "capabilityN"] 
default: TOP" "USER" "UIDL"* 
context:*main, server* 


With this directive you can set the list of POP3 protocol extensions presented to the client 
upon issuing the POP3 command CAPA. STLS is automatically added if you enable the 
starttls directive and SASL is added by the directive auth. 

使 用 这 条 指令 你 可 以 设置 POPS 协议 列表 来 扩展 现 有 客户 端 上 的 POP3 命 令 CAPA。 如 果 你 
启用 了 starttls 指 令 STLS 将 会 自动 被 添加 ， 通 过 auth，SASL 也 将 被 添加 。 


protocol 

syntax:*protocol*[ pop3 | imap | smtp ] ; 
default:*IMAP* 

context:*server* 

This directive set the protocol for this server block. 


这 条 指令 设置 了 服务 器 块 的 协议 


> server 


syntax:*server (...)* 
default:*no* 
context:*mail* 


Directive assigns configuration for the virtual server. 


指令 指定 虚拟 服务 器 的 配置 


There is no clear separation of the virtual servers ip-based and name-based (the value of 
the line "Host" header in the request). 


这 里 不 区 分 基于 IP 的 虚拟 服务 器 和 基于 命名 的 虚拟 服务 器 《Host 指 从 请 求 头 中 获得 ) 


Instead of this by directives listen are described all addresses and ports, on which it is 
necessary to assume connections for this server, and in directive server_name are indicated 
all names of servers. Example configurations are described in tuning of virtual servers. 

可 以 替代 这 个 的 listen 指 令 描 述 了 连接 服务 器 的 所 有 的 地 址 和 端口 ， 和 纸 条 指令 航 
server_name 显 示 了 所 有 的 服务 器 命名 。 例 如 以 下 配置 描述 了 虚拟 服务 器 的 调度 


server_name 


syntax:*server_name name*fqdn_server_host 
default:*The name of the host, obtained through gethostname()* 
context:*mail, server* 


Directive assigns the names of virtual server, for example: 


server { 
server name example.com www.example.com; 


} 


The first name becomes the basic name of server. By default the name of the machine 
(hostname) is used. It is possible to use "" for replacing the first part of the name: 


第 一 个 名 称 被 默认 为 服务 器 的 基本 名 词 .被 当 作 默 认 的 机 器 名 使 用 ,这 个 也 可 能 被 所 代 蔡 。 


server { 


server_name example.com *.example.com; 


} 


Two of the given name of the above example can be combined into one: 


2 个 给 定 的 名 词 在 以 上 的 例子 中 被 合并 成 一 个 


server { 
server name  .example.com; 


} 


The basic name of server is used in an HTTP redirects, if no a "Host" header was in client 
request or that header does not match any assigned servername. You can also use just "" to 
force Nginx to use the "Host" header in the HTTP redirect (note that "" cannot be used as the 
first name, but you can use a dummy name such as ™ instead): 


HTTP 重 定向 中 使 用 了 服务 器 基本 名 称 ， 如 果 客 户 端 请 求 中 没有 "host" 头 或 者 头 中 没 知 道 
servername. {RPI EL (s F8 “* "SE sg till Nginxt£HTT PSE AeA "Host" GER: "不 能 作为 
第 一 命名 可 以 使 用 “代替 ) 


server { 
server_name example.com *; 


server { 
server_name _ *; 


} 


smtp_auth 

syntax:*smtp_auth*[login] [plain] [cram-md5] ; 
default:*login plain* 

context:*main, server* 


With this directive you can set the permitted methods of authentication for SMTP clients: 
使 用 这 个 命令 你 可 以 设置 SMTP 客 户 端的 验证 方法 


e login - AUTH LOGIN 
e plain - AUTH PLAIN 
e cram-md5 - AUTH CRAM-MD5 


smtp_capabilities 

syntax:*smtp_capabilities*“capability1” [“capability2” .. “capabilityN”] 
default:*no* 

context:*main, server* 


With this directive you can set the list of SMTP protocol extensions presented to the client 
upon issuing the EHLO command. This list is automatically extended by the methods 
enabled with the directive smtp_ auth. 

使 用 这 条 指令 你 可 以 设置 SMTP 协 议 扩展 现 有 的 客户 端 通过 使 用 EHLO 命 邻 .使 用 smtp_auth 指 
今 这 个 列表 将 被 自动 扩展 。 


The current list of standardized SMTP expansions is published on www.iana.org . 现在 标准 
的 SMTP 扩 展 列表 发 布 在 www.iana.org 


so_keepalive 


syntax:*so keepalive*on|off, 


default:*off* 
context:*main, server* 


With this directive you can set the socket SO KEEPALIVE option for the connection to the 
IMAP/POP3 backend. In FreeBSD the keepalive option is used for all connections and can 
be turned off through setsockopt no (see sysctl net.inet.tcp.always keepalive). 

通过 使 用 这 条 指令 你 可 以 设置 socket 连 接 IMAP. POP3 的 SO 一 -KEEPALIVE 选 项 。 在 
FREEBSD 中 这 个 keepalive( 保 持 存 活 ) 选项 在 所 有 的 连接 中 都 有 效 并 且 可 以 使 用 setsockopt 
no 来 关闭 。 


timeout 


syntax:*timeout*milliseconds; 
default:*60000* 
context:*main, server* 


With this directive you can set the time out for proxied connections to the back end. 
使 用 这 条 指令 你 可 以 设置 代理 连接 的 超时 时 间 


MailAuth 


Example configuration 
配置 举例 : 


auth_http localhost :9000/cgi-bin/nginxauth.cgi; 
auth_http_timeout 5; 


auth_http 


syntax:*auth_http*URL 
default:*no* 
context:*mail, server* 


With this directive you can set the URL to the external HTTP-like server for authorization. A 
description of the protocol can be found here . 
使 用 这 条 指令 你 可 以 设置 URL 像 HTTP 服 务 器 那样 的 验证 。 协 议 描 述 可 以 看 这 里 


auth_http_header 


syntax:*auth_http_header*header value 
default:*no* 
context:*mail, server* 


With this directive you can add a HTTP header and value during the identification process. 
This makes it possible to use a shared secret to ensure that the request was answered by 
nginx. 

使 用 这 条 指令 你 可 以 添加 HTTP 头 和 值 到 验证 进程 中 。 这 个 使 得 可 以 用 共享 密码 来 却 不 请 求 得 
到 Nginx 的 响应 


For example: 


auth_http_header X-NGX-Auth-Key "secret_string"; 


auth_http_timeout 


syntax:*auth_http_timeout*milliseconds; 
default:*60000* 
context:*mail, server* 


With this directive you can set the time out for authentication process. 
使 用 这 条 指 合 你 可 以 设置 验证 进程 的 超时 时 间 


MailProxy 


Nginx can proxy IMAP, POP3, and SMTP protocols. 
Ngin 可 以 代理 IMAP，POP3 和 SMTP 协 议 


TES 


proxy 
syntax:*proxy*on | off 
default:*off* 
context:*mail, server* 


With this directive you can enable or disable the proxy for mail. 
使 用 这 条 指 倒 你 可 以 开启 和 关闭 邮件 代理 


proxy_buffer 


syntax:*proxy_buffer*size 
default:*AK/8K* 
context:*mail, server* 


With this directive you can set the buffer size for the proxy connection. The default value is 
equal to the size of a page (this can be either 4K or 8K depending on the platform). 

使 用 这 条 指令 你 可 以 设置 代理 连接 的 缓存 大 小 。 默 认 值 为 页 面 的 大 小 (这 个 根据 平台 的 不 同 可 
能 是 4K 或 者 8K) 


proxy_pass_error_message 


syntax:*proxy pass error message"*on | off 
default:*off* 
context:*mail, server* 


With this directive you can pass authentification error messages obtained from the backend 
back to the client. Usually if authorization in nginx passed successfully then the backend 
cannot return errors back to the client. 

通过 这 条 指 今 你 可 以 使 得 客户 端 忽略 从 后 端 获 得 的 验证 错误 消息 .通常 验证 成 不 会 返回 错误 消 
息 到 客户 端 。 


But for some POP3 servers errors in response to correct password is a regular behavior. For 
example CommuniGatePro notifies user about overcrowding of the mailbox (or other events) 
periodically issuing an error in authorization. In this case is worth indicating 
proxy_error_message on. 

但 是 在 POP3 服 务 器 中 错误 是 用 来 更 重 密码 。 例 如 CommuniGatePro 通过 验证 返回 邮箱 收 件 
箱 已 满 的 错误 来 通知 用 户 ， 这 样 的 代理 错误 信息 是 很 有 意义 的 。 


proxy_timeout 


syntax:*proxy_timeout*time 

default:*24h* 

context:*mail, server* 

With this directive you can set the timeout for the proxy connection. 


使 用 这 条 指令 你 可 以 设置 代理 连接 的 超时 时 间 。 


xclient 


syntax:*xclient*on | off 
default:*on* 
context:*mail, server* 


With this directive you can enable or disable the command XCLIENT with the connection to 
SMTP backend. This allows the backend to enforce limitations on the client based on 
IP/HELO/LOGIN. 

使 用 这 条 指令 你 可 以 开启 或 者 关闭 命令 XCLIENT 的 SMTP 后 端 连接 .这 个 使 得 后 端 强制 可 以 通 
过 IPHELO LOGIN 限 定 客 户 端 


If xclient is enabled then nginx first transfers to the backend: 
如 果 xclient 被 让 用 ，nginx 首 先 转 换 到 后 端 


EHLO Server_name 


Then: 


XCLIENT PROTO=ESMTP HELO=client_helo ADDR=client_ip LOGIN=authentificated_user NAME=[UNAV 


E 





MailSSL 


This module ensures SSL/TLS support for POP3/IMAP/SMTP. Configuration is practically 
identical to the configuration of the HTTP SSL module, but checking client certificates is not 
supported. 

这 个 模块 使 得 POP3.IMAP ~SMTP 可 以 使 用 SSLTLS. 配 置 已 经 定义 了 HTTP SSL 模 块 ， 但 
是 不 支持 客户 端 证 书 检测 。 

ssl 

syntax:*ssl*on | off 

default:*ssl off* 


context:*mail, server* 


Enables SSL/TLS for this virtual server. 
在 虚拟 服务 器 中 启用 SSLTLS 


ssl certificate 


syntax:"ssl certificate "file 
default:*cert.pem* 
context:*mail, server* 


Indicates file with the certificate in PEM format for this virtual server. The same file can 
contain other certificates, and also secret key in PEM format. 

显示 虚拟 服务 器 上 的 PEM 格 式 的 证 书 文件 。 同 一 文件 可 以 包含 其 他 的 证 书 和 包含 PEM 格 式 的 
安全 码 。 


ssl_certificate_key 


syntax:*ssl_certificate_key *file 
default:*cert.pem* 
context:*mail, server* 


Indicates file with the secret key in PEM format for this virtual server. 


显示 虚拟 服务 器 中 PEM 格 式 的 安全 码 文件 


ssl_ciphers 


syntax:"ssl ciphers file*ciphers 
default:*ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP* 
context:*mail, server* 


Directive describes the permitted ciphers. Ciphers are assigned in the formats supported by 
OpenSSL. 
指令 描述 了 容许 的 SSL chiphers.chiphers 都 被 使 用 了 OpenSSL 支 持 的 格式 . 


ss| prefer server ciphers 


syntax:*ssl prefer server ciphers*on | off 
default:*off* 
context:*mail, server* 


Requires protocols SSLv3 and TLSv1 server ciphers be preferred over the client's ciphers. 
需要 SSLv3 协 议 ,TLSv1 服务 器 端 米 阿 么 优先 于 客户 端 密码 


ss| protocols 


syntax:*ssl_protocols*/SSLv2] [SSLv3] [TLSv1] 
default:*SSLv2 SSLv3 TLSv1* 

context:*mail, server* 

Directive enables the protocols indicated. 


指令 显示 协议 


ss| session cache 


syntax:*ss| session cache"[builtin[:size [shared:name:size] 
default:*builtin:20480* 
context:*mail, server* 


The directive sets the types and sizes of caches to store the SSL sessions. 
指 合 设置 了 类 型 和 存储 SSL 会 话 的 缓存 的 大 小 . 

The cache types are: 

缓存 类 型 为 : 


e builtin -- the OpenSSL builtin cache, is used inside one worker process only. The cache 
size is assigned in the number of the sessions. 


builtin -- OpenSSL 内 部 缓存 ,这 个 只 在 内 部 工作 进程 中 被 使 用 .这 个 缓存 大 小 等 同 于 会 话 的 
个 数 。 

e shared -- the cache is shared between all worker processes. The size of cache is 
assigned in the bytes, 1 MB cache can contain about 4000 sessions. Each shared 
cache must have arbitrary name. Cache with the same name can be used in several 
virtual servers. 
shared -- 这 个 缓存 被 所 有 工作 进程 共享 .这 个 缓存 大 小 用 字 节 标识 ,1M 缓 存 可 以 包含 大 约 
4000 个 会 话 。 每 个 共享 缓存 都 有 专 有 的 名 称 。 相 同名 称 的 缓存 可 以 被 多 个 服务 器 使 用 。 


It is possible to use both types of cache simultaneously, for example: 
可 能 同时 使 用 2 中 类 型 的 缓存 ， 例 如 


ssl_session_cache builtin:1000 shared:SSL:10m; 


However, the only shared cache usage without that builtin should be more effective. 


然而 ， 共 享 缓存 只 有 在 内 部 缓存 之 外 使 用 才能 产生 更 好 的 效果 。 


ss| session timeout 


syntax:*"ss| session timeout*time 
default:*5m* 
context:*mail, server* 


Assigns the time during which the client can repeatedly use the parameters of the session, 
which is stored in the cache. 


在 使 用 中 客户 端 重复 使 用 的 会 话 参数 被 存储 在 缓存 中 。 


starttls 


syntax:*starttls on | off | only* 
default:*off* 
context:*mail, server* 


e on - permit the use of commands STLS for POP3 and STARTTLS for IMAP/SMTP 
on - 容许 在 POP3 中 的 STLS 命 信和 IMAP ~SMPT 中 的 STARTTLS 命 兮 

e off - do not allow command STLS/STARTTLS 
不 容许 STLS/STARTTLS #849 

e only - announce STLS/STARTTLS support and require that clients use TLS encryption 
only - 宣布 支持 STLSSTARTTLS 但 是 需要 客户 端 使 用 TLS 加 密 
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nginx 在 windows 上 的 安装 
下 简单 的 安装 方法 
1. 下 载 软 件 
需要 的 软件 有 nginx,php,mysql( 如 不 需要 可 不 安装 ) 
nginx.org,www.php.net 上 面 有 得 下 
全 部 解压 出 来 
php 基 本 不 用 做 任何 修改 〈 下 载 直 接 解压 版 本 的 ) 
2. 配 置 nginx 


只 需 修 改 一 行 (nginx/conf/nginx.conf) 


fastcgi param SCRIPT_FILENAME d:/nginx/html/$fastcgi script name; 


找到 大 概 这 一 行 修 改 路 径 最 好 是 绝对 路 径 〈 相 对 路 径 可 以 自行 探讨 ) 
3. 运 行 软件 

先 运 行 php 

程序 》 运 行 》cmd 

到 php 所 在 目录 运行 下 面 代码 


php-cgi.exe -b 127.0.0.1:9000 -c php\php.ini 
再 运行 nginx 
到 nginx 所 在 目录 

nginx.exe -c conf\nginx.conf 
这 样 就 ok 了 。 


win 下 可 以 使 用 NPMserv 更 强大 


by afen.cn 


nginx 在 freebsd 上 的 安装 
一 . 安装 必 各 软件 MySQL+PHP+Pcre 


cd /usr/ports/database/mysql50-server && make install clean 
cd /usr/lang/php5/ && make install clean 选择 对 cgi mysql 等 的 支持 
cd /usr/devel/pcre && make install clean 


用 ports 安 装 /usr/ports/www/nginx, make install clean 
二 、 弄 了 一 个 fastcgi 的 脚本 ， 来 自 lighttpd 


cd /usr/ports/www/lighttpd 

make 

cp /usr/ports/www/lighttpd/work/lighttpd-1.4.18/src/spawn-cgi /usr/bin 
make clean 


三 、 修 改 配置 文件 : 


1,/usr/local/etc/nginx/nginx.conf: 


user www WWW; 
worker_processes 10; 
error_log /usr/local/etc/nginx/logs/nginx_error.log crit; 
worker_rlimit_nofile 51200; 
events 
{ 
use epoll; 
worker_connections 51200; 
} 
http 
{ 
include conf/mime.types; 
default_type application/octet-stream; 
charset gb2312; 
server_names_hash_bucket_size 128; 
keepalive_timeout 60; 
tcp_nodelay on; 
gzip on; 
gzip min length 1k; 
gzip buffers 4 8k; 
gzip http version 1.1; 
gzip types text/plain application/x-javascript. text/css text/html application/xml; 
server 
2 
listen 80; 
server name www.test.com; 
index index.html index.htm index.php; 
root /usr/local/www/data/; 
location ~ .*\.php?$ 





include fcgi.conf; 

fastcgi pass 127.0.0.1:9000; 

fastcgi index index.php; 

j 

log format access '$remote addr - $remote user [$time local] "$request" ' 
'$status $body bytes sent "$http referer" ' 


'"$http user agent" $http x forwarded for'; 
access log /usr/local/nginx/logs/access.log access; 


} 
} 


Aoo: O 


2 , 先 将 php.ini 的 配置 中 cgi.fix_pathinfo=1 这 样 php-cgi 方 能 正常 使 用 SCRIPT_FILENAME 这 个 


t£. 


3, 编 辑 fcgi.conf 文 件 ,加 入 


fastcgi_param GATEWAY_INTERFACE CGI/1.1; 
fastcgi_param SERVER_SOFTWARE nginx; 


fastcgi param QUERY STRING $query_string; 
fastcgi param REQUEST METHOD . $request method; 
fastcgi param CONTENT TYPE . $content type; 
fastcgi param CONTENT LENGTH $content length; 


fastcgi param SCRIPT FILENAME X $document root$fastcgi script name; 
fastcgi param SCRIPT NAME  $fastcgi script name; 

fastcgi param REQUEST URI $request uri; 

fastcgi param DOCUMENT URI $document uri; 

fastcgi param DOCUMENT_ROOT  $document root; 

fastcgi param SERVER PROTOCOL . $server protocol; 


fastcgi param REMOTE_ADDR $remote_addr; 
fastcgi param REMOTE PORT  $remote port; 
fastcgi param SERVER_ADDR $server addr; 
fastcgi param SERVER PORT  J $server port; 
fastcgi param SERVER NAME X $server name; 


# PHP only, required if PHP was built with --enable-force-cgi-redirect 
Zfastcgi param REDIRECT STATUS 200; 


四 ,启动 


1, 启动 fcgi 


/usr/bin/spawn-fcgi -a 127.0.0.1 -p 9000 -u ww -f /usr/local/bin/php-cgi 


参数 说 明 : 


二 指定 调用 FastCGI 的 进程 的 执行 程序 位 置 ， 根 据 系统 上 所 装 的 PHP 的 情况 具体 设置 

-a 绑 定 到 地 址 addr 

-p 绑 定 到 端口 port 

-s 绑 定 到 unix socket 的 路 径 path 

-C 指定 产生 的 FastCGI 的 进程 数 ， 默 认为 5 〈 仅 用 于 PHP) 

-P 指定 产生 的 进程 的 PID 文 件 路 径 

-U 和 -g FastCGI 使 用 什么 身份 (-u 用 户 -g 用 户 组 ) 运行 ，Ubuntu 下 可 以 使 用 www-data， 其 
他 的 根据 情况 配置 ， 如 nobody、apache 等 


也 可 建立 脚本 


1) ee /usr/bin/php-fastcgi 


#!/bin/sh 


/usr/bin/spawn-fcgi -a 127.0.0.1 -p 9000 -u ww -f /usr/local/bin/php-cgi 


2)c hmod 755 /usr/bin/php-fastcgi 


3) ee /usr/local/etc/rc.d/init-fastcgi 


#!/bin/bash 


PHP SCRIPT-/usr/bin/php-fastcgi 
RETVAL=0 

case "$1" in 
start) 
$PHP_SCRIPT 
RETVAL=$? 
stop) 

killall -9 php 
RETVAL=$? 
restart) 
killall -9 php 
$PHP_SCRIPT 
RETVAL=$? 


D 

echo "Usage: php-fastcgi {start|stop|restart}" 
exit 1 

esac 

exit $RETVAL 


4) chmod 755 /usr/local/etc/rc.d/init-fastcgi 


2, 8 shnginx 
nginx -t -c /usr/local/etc/nginx/nginx.conf 测试 配置 是 否 正 确 
如 果 屏 幕 显示 以 下 两 行 信息 ， 说 明 配 置 文件 正确 : 


the configuration file /usr/local/etc/nginx/nginx.conf syntax is ok 
the configuration file /usr/local/etc/nginx/nginx.conf was tested successfully 


Ba: 


nginx -c /usr/local/etc/nginx/nginx.conf 


开机 自动 启动 加 入 /etc/rc.conf 


nginx_enable="YES" 


nginx 参 数 : 

-c </path/to/config> 为 Nginx 指定 一 个 配置 文件 ， 来 代 蔡 缺 省 的 。 

-t 不 运行 ， 而 仅仅 测试 配置 文件 。nginx 将 检查 配置 文件 的 语法 的 正确 性 ， 并 党 试 打开 配置 文 
件 中 所 引用 到 的 文件 。 

-V 显 示 nginx 的 版 本 。 

-V 显 示 nginx 的 版 本 ， 编 译 器 版 本 和 配置 参数 。 


nginx 在 ubuntu 上 的 安装 
1、 安 装 Nginx 
apt-get install nginx 


(要 最 新 版 本 下 载 下 来 编译 吧 ) 
装 完 应 该 能 正常 运行 了 。 如 果 之 前 有 装 APACHE 要 改 下 端口 。。。 或 者 直接 


apt-get remove apache2 
/etc/init.d/nginx stop 
/etc/init.d/nginx start 


2、 安 装 php-cgi 


apt-get install php-cgi 


(要 自 定义 安装 的 编译 吧 ) 
3、 改 php-cgi 的 配置 


Ubuntu 下 是 /etc/php5/cgi/php.ini 
之 前 有 安装 过 php 的 话 会 复制 apache 的 配置 文件 
打开 cgi.fix_pathinfo 选 项 : 


cgi.fix pathinfo-1; 


4、 改 Nginx 的 fastcgi 传 递 参数 


Ubuntu 下 是 /etc/nginx/fastcgi_params 
默认 应 该 已 经 设置 好 了 ， 内 容 差 不 多 就 下 面 那样 : 


代码 : 


fastcgi_param 
fastcgi_param 
fastcgi_param 
fastcgi_param 
fastcgi_param 
fastcgi_param 
fastcgi_param 
fastcgi_param 
fastcgi_param 
fastcgi_param 
fastcgi_param 
fastcgi_param 
fastcgi_param 
fastcgi_param 
fastcgi_param 
# PHP only, 
fastcgi_param 


QUERY_STRING $query_string; 
REQUEST_METHOD $request_method; 
CONTENT_TYPE $content_type; 
CONTENT_LENGTH $content_length; fastcgi_param SCRIPT_NAME $fastcgi_script_na 
REQUEST_URI $request_uri; 
DOCUMENT_URI $document_uri; 
DOCUMENT_ROOT $document_root; 
SERVER_PROTOCOL $server_protocol; 
GATEWAY_INTERFACE CGI/1.1; 
SERVER_SOFTWARE nginx/$nginx_version; 
REMOTE_ADDR $remote_addr; 

REMOTE_PORT $remote_port; 

SERVER_ADDR $server_addr; 

SERVER_PORT $server_port; 

SERVER_NAME $server_name; 


required if PHP was built with -enable-force-cgi-redirect 


REDIRECT_STATUS 200; 


ES 


5、 创 建 VHost 配 置 (这 里 只 说 Ubuntu 下 的 ， 也 就 路 径 和 包含 文件 目录 的 区 别 了 ) 
在 /etc/nginx/sites-available/ 下 创建 服务 器 配置 文件 比如 myserver 





ln -n /etc/nginx/sites-available/myserver /etc/nginx/sites-enabled/myserver 


其 实 懒 的 话 直接 创建 在 enabled 里 也 没 问 题 一 。 一 
内 容 填 : 


代码 : 


server { 

listen 80; 

server name myserver.com; 

access log /var/log/nginx/myserver.access.log;location / { 
root /wwwroot/myserver; 

index index.php; 

autoindex off; 

} 

location ~ \.php$ { 

include /etc/nginx/fastcgi_params; 

fastcgi param SCRIPT FILENAME /wwwroot/myserver/$fastcgi script name; 
fastcgi pass 127.0.0.1:9000; 

fastcgi index index.php; 

} 

# redirect server error pages to the static page /50x.html 
error page 500 502 503 504 /50x.html; 


location = /50x.html { 
root /var/www/nginx-default; 
} 


# deny access to .htaccess files, if Apache’s document root 
location ~ /\.ht { 

deny all; 

} 

} 


6、 安 装 spawn-fcgi 


下 载 可 到 这 里 ， 这 东西 已 经 独立 出 来 了 
http://redmine.lighttpd.net/projects/spawn-fcgi/wiki 
下 完 后 解压 编译 


sudo ./configure -prefix=/usr/local 
sudo make 
sudo make install 


7T. Æ s9»spaw-fcgi 


sudo spawn-fcgi -a 127.0.0.1 -p 9000 -u www-data -g www-data -f /usr/bin/php5-cgi -F 10 
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/etc/init.d/nginx restart 


9、 定 义 下 hosts 就 可 以 看 结果 啦 
编辑 /etc/hosts 加 入 


127.0.0.1 myserver.com 


然后 打开 浏览 器 就 可 以 看 结果 啦 ~~ 
有 问题 欢迎 指出 一 ~ 


nginx 在 fedora 上 的 安装 


原理 : 
安装 nginx 没 什么 好 说 的 ， 安 装 php-cig, 让 lighthttp 的 spawn-fcgi 对 其 进行 管理 


1. 用 yum 仓 库 安装 所 需 的 软件 


#yum install -y php php-cgi nginx lighttpd-fastcgi 


2. 生 成 php-cgi 的 环境 变量 配置 文件 


# vim /etc/nginx/fastcgi_params 


输入 以 下 内 容 ， 并 把 该 文件 设置 为 相应 属性 ， 可 以 设置 为 0777 


astcgi_param GATEWAY INTERFACE CGI/1.1; 


fastcgi param 
fastcgi param 
fastcgi param 
fastcgi param 
fastcgi param 
fastcgi param 
fastcgi param 
fastcgi param 
fastcgi param 
fastcgi param 
fastcgi param 
fastcgi param 
fastcgi param 
fastcgi param 
fastcgi param 
fastcgi param 


SERVER SOFTWARE nginx; 

QUERY. STRING $query. string; 
REQUEST METHOD $request method; 
CONTENT TYPE $content type; 
CONTENT LENGTH $content length; 
SCRIPT FILENAME $document root$fastcgi script name; 
SCRIPT NAME $fastcgi script name; 
REQUEST URI $request uri; 
DOCUMENT URI $document uri; 
DOCUMENT ROOT $document root; 
SERVER PROTOCOL $server protocol; 
REMOTE ADDR $remote addr; 

REMOTE PORT $remote port; 
SERVER_ADDR $server addr; 

SERVER PORT $server port; 

SERVER NAME $server name; 


# PHP only, required if PHP was built with -enable-force-cgi-redirect 
fastcgi param REDIRECT STATUS 200; 


3. 使 用 spawn-fcgi 来 控制 php-fastcgi 的 进程 

# /usr/bin/spawn-fcgi -a 127.0.0.1 -p 9000 -C 200 -u nginx -g nginx -f /usr/bin/php-cgi 
SSS SS SS SS ee 4/3] 
其 中 ，a 绑 定 的 地 址 ，p 是 端口 


-C 是 PHPCGI 的 进程 数 ,一 般 根据 自己 服务 器 的 内 存 大 小 设置 ，4G 服 务 器 ， 如 果 是 纯 
WEBSERVER 的 ， 可 以 设置 200 左 右 


4. 增 加 server 


# vim /etc/nginx/nginx.conf 
server{ 
listen 80; 
server name pylong.com [www.pylong.com](http://www.pylong.com/);# 多 个 域名 ， 用 空格 分 开 
index index.html index.php index.htm; 
root /var/www/pylong.com; 
location ~ .*.php$ 


include /etc/nginx/fastcgi_params; 
fastcgi_pass 127.0.0.1:9000; 


} 
} 


一 些 更 加 详细 的 conf 设 置 请 参看 nginx 的 维基 ， 以 及 相关 资料 
一 些 提 示 : 

yum 安 装 的 nginx, 相 关 命令 :servie nginx start|stop|reload 

把 nginx 添 加 到 系统 启动 项 里 : chkconfig nginx on 

其 中 ，a 绑 定 的 地 址 ，p 是 端口 


-C 是 PHPCGI 的 进程 数 ,一 般 根据 自己 服务 器 的 内 存 大 小 设置 ，4G 服 务 器 ， 如 果 是 纯 
WEBSERVERRS, WIL ii 20048 


4. 增 加 server 


# vim /etc/nginx/nginx.conf 
server{ 
listen 80; 
server name pylong.com [www.pylong.com](http://www.pylong.com/);# 多 个 域名 ， 用 空格 分 开 
index index.html index.php index.htm; 
root /var/www/pylong.com; 
location ~ .*.php$ 


include /etc/nginx/fastcgi_params; 
fastcgi_pass 127.0.0.1:9000; 


} 
} 


一 些 更 加 详细 的 conf 设 置 请 参看 nginx 的 维基 ， 以 及 相关 资料 
一 些 提 示 : 

yum 安 装 的 nginx, 相 关 命令 :servie nginx start|stop|reload 

把 nginx 添 加 到 系统 启动 项 里 : chkconfig nginx on 


让 spawn-fcgi 随 系统 自动 启动 。 


vim /etc/rc.loal 


在 文件 最 后 加 上 


# /usr/bin/spawn-fcgi -a 127.0.0.1 -p 9000 -C 200 -u nginx -g nginx -f /usr/bin/php-cgi 


»] 





E 
如 果 php 的 session 不 可 用 ， 一 般 是 因为 /var/lib/php/session 这 个 目录 的 对 于 nginx 不 可 写 ， 把 
它 所 有 者 改 为 nginx 相 应 用 户 已 经 用 户 组 





转载 请 注 明 地 址 :http://www.pylong.com/?p=6 


nginx php-fpm 安 装配 置 


nginx 本 身 不 能 义理 PHP， 它 只 是 个 web 服 务 器 ， 当 接收 到 请 求 后 ， 如 果 是 php 请 求 ， 则 发 给 
php 解 释 器 处 理 ， 并 把 结果 返回 给 客户 端 。 


nginx 一 般 是 把 请 求 发 fastcgi 管 理 进 程 处 理 ，fascgi 管 理 进程 选择 cgi 子 进程 处 理 结果 并 返回 被 
nginx 


本 文 以 php-fpm 为 例 介 绍 如 何 使 nginx 支 持 PHP 
一 、 编 译 安装 php-fpm 
什么 是 PHP-FPM 


PHP-FPM 是 一 个 PHP FastCGI 管 理 器 ， 是 只 用 于 PHP 的 ,可 以 在 http://php-fpm.org/download 
FREI. 


PHP-FPM 其 实 是 PHP 源 代码 的 一 个 补丁 ， 绅 在 将 FastCGI 进 程 管理 整合 进 PHP 包 中 。 必 须 将 
它 patch 到 你 的 PHP 源 代码 中 ， 在 编译 安装 PHP 后 才 可 以 使 用 。 


新 版 PHP 已 经 集成 php-fpm 了， 不 再 是 第 三 方 的 包 了 ， 推 荐 使 用 。PHP-FPM 提 供 了 更 好 的 
PHP 进 程 管理 方式 ， 可 以 有 效 控制 内 存 和 进程 、 可 以 平滑 重 载 PHP 配 置 ， 比 spawn-fcgi 具 有 更 
多 优点 ， 所 以 被 PHP 官 方 收录 了 。 在 ./configure 的 时 候 带 -enable-fpm 参 数 即 可 开启 PHP- 
FPM， 其 它 参 数 都 是 配置 php 的 ， 具 体 选项 含义 可 以 查看 这 里 。 


安装 前 准备 
centos 下 执行 


yum -y install gcc automake autoconf libtool make 

yum -y install gcc gcc-c++ glibc 

yum -y install libmcrypt-devel mhash-devel libxslt-devel \ 

libjpeg libjpeg-devel libpng libpng-devel freetype freetype-devel libxml2 libxml2-devel \ 
Zlib zlib-devel glibc glibc-devel glib2 glib2-devel bzip2 bzip2-devel \ 


ncurses ncurses-devel curl curl-devel e2fsprogs e2fsprogs-devel \ 
krb5 krb5-devel libidn libidn-devel openssl openssl-devel 


| 


新 版 php-fpm 安 装 (推荐 安装 方式 ) 


wget http://cn2.php.net/distributions/php-5.4.7.tar.gz 

tar zvxf php-5.4.7.tar.gz 

cd php-5.4.7 

./configure --prefix-/usr/local/php --enable-fpm --with-mcrypt \ 
--enable-mbstring --disable-pdo --with-curl --disable-debug --disable-rpath \ 
--enable-inline-optimization --with-bz2  --with-zlib --enable-sockets \ 
--enable-sysvsem --enable-sysvshm --enable-pcntl --enable-mbregex \ 
--with-mhash --enable-zip --with-pcre-regex --with-mysql --with-mysqli \ 
--with-gd --with-jpeg-dir 


make all install 





以 上 两 种 方式 都 可 以 安装 php-fpm， 安 装 后 内 容 放 在 /usr/local/php 目 录 下 


以 上 就 完成 了 php-fpm 的 安装 。 


下 面 是 对 php-fpm 运 行 用 户 进行 设置 


cd /usr/local/php 
cp etc/php-fpm.conf.default etc/php-fpm. conf 
vi etc/php-fpm. conf 


修改 


user = www-data 
group = www-data 


如 果 www-data 用 户 不 存在 ， 那 么 先 添加 www-data 用 P 


groupadd www-data 
useradd -g www-data www-data 


二 、 编 译 安装 nginx 

然后 按照 http://www.nginx.cn/install 安装 nginx 

三 、 修 改 nginx 配 置 文件 以 支持 php-fpm 
nginx 安 装 完成 后 ， 修 改 nginx 配 置 文件 为 ,nginx.conf 


其 中 server 段 增加 如 下 配置 ， 注 意 标 红 内 容 配 置 ， 否 则 会 出 现 No input file specified. 错 误 


# pass the PHP scripts to FastCGI server listening on 127.0.0.1:9000 
# 

location ~ \.php$ { 

root html; 

fastcgi pass 127.0.0.1:9000; 

fastcgi index index.php; 

fastcgi param SCRIPT FILENAME $document root$fastcgi script name; 
include fastcgi params; 


} 


四 、 创 建 测试 php 文 件 
创建 php 文 件 


在 /usrlocalnginx/html 下 创建 index.php 文 件 ， 输 入 如 下 内 容 


<?php 
echo phpinfo(); 
?> 


五 、 启动 服务 
启动 php-fpm 和 nginx 
/usr/local/php/sbin/php-fpm 


# 手 动 打 补丁 的 启动 方式 /usr/local/php/sbin/php-fpm start 


sudo /usr/local/nginx/nginx 
php-fpm 关 闭 重启 见 文章 结尾 
六 、 浏 览 器 访问 


访问 http:// 你 的 服务 器 ip/index.php， 此 可 以 见 到 php 信 息 了 。 
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安装 php-fpm 时 可 能 遇 到 的 错误 : 
1. php configure 时 出 错 


configure: error: XML configuration could not be found 


apt-get install libxml2 libxml2-dev (ubuntu 下 ) 
yum -y install libxml2 libxml2-devel (centos F) 


1. Please reinstall the BZip2 distribution 


wget http://www.bzip.org/1.0.5/bzip2-1.0.5.tar.gz 
tar -zxvf bzip2-1.0.5.tar.gz 

cd bzip2-1.0.5 

make 

make install 


1，php 的 配置 文件 中 有 一 行 --with-mysql=/usr。 


安装 的 时 候 提示 : 


configure: error: Cannot find MySQL header files under yes. 
Note that the MySQL client library is not bundled anymore. 


这 是 由 于 安装 mysql 时 没有 安装 mysql 头 文件 ， 或 者 是 路 径 指定 不 正确 ,php 找 不 到 mysqdlI 的 头 文 
件 引 起 的 错误 提示 。 
解决 方法 。 
(1.) 查看 你 的 系统 有 没有 安装 mysql header 
find / -name mysql.h 
如 果 有 。 请 指定 --with-mysql=/ 跟 你 的 正常 路 径 。 


如 果 没 有 。 请 看 下 一 步 。 


(2.)redhat 安 装 


rpm -ivh MySQL-devel-4.1.12-1.1386.rpm 


We 
| 


nginx php-fpm 安 委 


(3.)ubuntu 安 装 


apt-get install libmysqlclient15-dev 


(4.) 最 后 一 步 php 的 配置 选项 添加 --with-mysql=/usr 即 可 ! 


4.No input file specified. 


location ~ \.php$ { 

root html; 

fastcgi_pass 127.0.0.1:9000; 

fastcgi_index index.php; 

fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; 
include fastcgi_params; 


} 


1. 如果 php configure 时 缺 库 ， 可 以 先 安装 库 (ubuntu 下 ) 


sudo apt-get install make bison flex gcc patch autoconf subversion locate 
sudo apt-get install libxml2-dev libbz2-dev libpcre3-dev libssl-dev zlibig-dev libmcrypt- 





1. mcrypt.h not found. Please reinstall libmcrypt 


apt-get install libmcrypt-dev 


或 者 


cd /usr/local/src 

wget http://softlayer.dl.sourceforge.net/sourceforge/mcrypt/libmcrypt-2.5.8.tar.gz 
tar -zxvf libmcrypt-2.5.8.tar.gz 

cd /usr/local/src/libmcrypt-2.5.8 

./configure --prefix-/usr/local 

make 

make install 


1. php-fpm 5.4.7 如 何 关 闭 BA? 


php 5.4.7 下 的 php-fpm 不 再 支持 php-fpm 以 前 具有 的 /usr/local/php/sbin/php-fpm 
(startlstop|reload) 等 命 舍 ， 需 要 使 用 信号 控制 : 


master 进 程 可 以 理解 以 下 信号 


INT, TERM 立刻 终止 QUIT 平滑 终止 USR1 重新 打开 日 志文 件 USR2 平滑 重 载 所 有 worker 进 
程 并 重新 载 入 配置 和 二 进 制 模块 


示例 : 


php-fpm 关闭 : 


kill -INT ‘cat /usr/local/php/var/run/php-fpm.pid' 


php-fom 重启 : 


kill -USR2 ‘cat /usr/local/php/var/run/php-fpm.pid^ 


查看 php-fpm 进 程 数 : 
ps aux | grep -c php-fpm 
8. 命 令 行 下 执行 php， 提 示 找 不 到 命 兮 


-bash: /usr/bin/php: No such file or directory 


vi /etc/profile 


在 文件 底部 增加 一 行 配 置 


export PATH-/usr/local/php/bin:$PATH 


保存 退出 


source /etc/profile 


配置 示例 和 方法 


完整 例子 


两 个 虚拟 主机 ( 纯 静 态 -html 支持 ) - Two Virtual Hosts, Serving 
Static Files 


wies 1 

: server ( 

: listen 80; 

: server name www.domaini.com; 

: access log logs/domaini.access.log main; 


: location / { 
: index index.html; 
: root /var/www/domaini.com/htdocs; 


: 3 

: server { 

: listen 80; 

: server_name www.domain2.com; 

: access log logs/domain2.access.log main; 


: location / { 

: index index.html; 

: root /var/www/domain2.com/htdocs; 
: 3 

: 4 

} 


虚拟 主机 标准 配置 (简化 ) - A Default Catchall Virtual Host 


ER { 

: server { 

: listen 80 default; 

: server_name pr 

: access log logs/default.access.log main; 


: location / { 

: index index.html; 

: root /var/www/default/htdocs; 
: 3 

Boy 

} 


在 父 文件 夹 中 建立 子 文件 夹 以 指向 子 域名 -Wildcard 


Subdomains in a Parent Folder 


这 是 一 | 个 添加 子 域名 (或 是 当 DNS 已 指 向 服务 器 时 添加 一 个 新 域名 ) 的 简 单方 法 。 需要 注意 的 
是 ， 我 已 经 将 FCGI 配 置 进 该 文件 了 。 如 果 你 只 想 使 服务 器 为 静态 文件 服务 ， 可 以 直接 将 FCGI 
配置 信息 注释 掉 ， 然 后 将 默认 主页 文件 变 成 index.html。 


这 个 简单 的 方法 比 起 为 每 一 个 域名 建立 一 个 vhost.conf 配置 文件 来 讲 ， 只 需要 在 现 有 的 配置 
文件 中 增加 如 下 内 容 : 


This is just a really easy way to keep adding new subdomains, or to add new domains 
automatically when DNS records are pointed at the server. Note that | have included FCGI 
here as well. If you want to just serve static files, strip out the FCGI config and change the 
default document to index.html. Rather than creating a new vhost.conf file for every domain, 
just create one of these: 


server { 

: # Replace this port with the right one for your requirements 

: # 根据 你 的 需求 改变 此 端口 

: listen 80; #could also be 1.2.3.4:80 也 可 以 是 1.2.3.4:80 的 形式 
: # Multiple hostnames seperated by spaces. Replace these as well. 

: # 多 个 主机 名 可 以 用 空格 隔 开 ， 当 然 这 个 信息 也 是 需要 按照 你 的 需求 而 改变 的 。 

: server name star.yourdomain.com *.yourdomain.com www.*.yourdomain.com; 
: #Alternately: — * 

: # 或 者 可 以 使 用 : _ * (具体 内 容 参 见 本 维基 其 他 页 面 ) 

: root /PATH/TO/WEBROOT/$host; 

: error page 404 http://yourdomain.com/errors/404.html; 
: access log logs/star.yourdomain.com.access.1log; 

: location / { 

: root /PATH/TO/WEBROOT/$host/; 

: index index.php; 

ue 

: # serve static files directly 

: # 直接 支持 静态 文件 (从 配置 上 看 来 不 是 直接 支持 啊 ) 

: location -* 4.+.(jpg|jpeg|gif|css|png|js|ico|html)$ { 


: access log off; 
: expires 30d; 
: 3 


: location ~ .php$ { 

: # By all means use a different server for the fcgi processes if you need to 
: # 如 果 需 要 ， 你 可 以 为 不 同 的 FCGI 进 程 设置 不 同 的 服务 信息 

: fastcgi_pass 127.0.0.1: YOURFCGIPORTHERE ; 

: fastcgi_index index.php; 

: fastcgi_param SCRIPT_FILENAME /PATH/TO/WEBROOT/$host/$fastcgi_script_name; 


: fastcgi_param QUERY_STRING $query_string; 
: fastcgi_param REQUEST_METHOD $request_method; 
: fastcgi_param CONTENT_TYPE $content_type; 


: fastcgi_param CONTENT_LENGTH $content_length; 
: fastcgi_intercept_errors on; 

z} 

: location ~ /\.ht { 

: deny all; 

2 

: } 


完整 例子 2 
这 是 来 自 Nginx 官 方 网 站 的 一 个 例子 。 


#!nginx 

: # 使 用 的 用 户 和 组 

: user Www www; 

: # 指定 工作 衍生 进程 数 

: worker_processes 2; 

: # 指定 pid 存放 的 路 径 

: pid /var/run/nginx. pid; 


: # [ debug | info | notice | warn | error | crit ] 
: # 可 以 在 下 方 直接 使 用 [ debug | info | notice | warn | error | crit ] 参数 
: error log /var/log/nginx.error log info; 


: events { 
DOR 人 允许 的 连接 数 
: Connections 2000; 
: # use [ kqueue | rtsig | epoll | /dev/poll | select | poll ] ; 
: # 具体 内 容 查看 http://wiki.codemongers.com/ 事 件 模 型 
use kqueue; 


} 


http { 
include conf/mime.types; 
default type application/octet-stream; 


: log format main '$remote addr - $remote user [$time local] ' 
'"$request" $status $bytes sent ' 
'"$http referer" "$http user agent" ' 
'"$gzip ratio"'; 


: log format download '$remote_addr - $remote user [$time local] ' 
'"$request" $status $bytes sent ' 
'"$http referer" "$http user agent" ' 
'"$http range" "$sent http content range"'; 


client header timeout 3m; 


: client body timeout 3m; 
send timeout 3m; 
client header buffer size 1k; 





: large client header buffers 4 4k; 





gzip on; 

gzip min length 1100; 

gzip buffers 4 8k; 

gzip types text/plain; 


: output buffers 1 32k; 
postpone output 1460; 


sendfile on; 
tcp nopush on; 
tcp nodelay on; 
send lowat 12000; 


keepalive timeout 75 20; 


: Zlingering time 30; 
: Z4lingering timeout 10; 
: 4&reset timedout connection on; 


: server ( 
: listen one.example.com; 


server name one.example.com www.one.example.com; 
: access log /var/log/nginx.access log main; 


location / { 


proxy_pass http://127.0.0.1/; 
proxy_redirect off; 

proxy_set_header Host $host; 
proxy_set_header X-Real-IP $remote_addr; 


: #proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; 


: client_max_body_size 10m; 
: client_body_buffer_size 128k; 


: client body temp path /var/nginx/client body temp; 
proxy connect timeout 90; 
proxy send timeout 90; 
proxy read timeout 90; 
proxy send lowat 12000; 
proxy buffer size 4k; 
proxy_buffers 4 32k; 


proxy_busy_buffers_size 64k; 
proxy temp file write size 64k; 





proxy temp path /var/nginx/proxy temp; 


charset  koi8-r; 


} 


error_page 404 /404.html; 


location /404.html { 
root /spool/www; 


charset on; 
source_charset koi8-r; 


location /old_stuff/ { 
rewrite ^/old stuff/(.*)$ /new_stuff/$1 permanent; 


j 


location /download/ { 
: valid referers none blocked server names *.example.com; 


: if ($invalid_referer) { 
: #rewrite A/ http://www.example.com/; 
return 403; 


: 3 


: #rewrite_log on; 


: # rewrite /download/*/mp3/*.any ext to /download/*/mp3/* .mp3 
: rewrite ^/(download/.*)/mp3/(.*)N..*$ 


/$1/mp3/$2.mp3 break; 
: root / spool/www; 
: #autoindex on; 


: access log /var/log/nginx-download.access log download; 


d 
location -* 4.+\.(jpg|jpeg|gif)$ { 


: root / spool/www; 
: access log off; 
expires 30d; 
} 
} 


} 
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虚拟 主机 


两 个 虚拟 主机 ( 纯 静 态 -html 支持 ) - Two Virtual Hosts, Serving 
Static Files 


wies 1 


: server ( 

: listen 80; 

: server name www.domaini.com; 

: access log logs/domaini.access.log main; 


: location / { 
: index index.html; 
: root /var/www/domaini.com/htdocs; 


: 3 

: server { 

: listen 80; 

: server_name www.domain2.com; 

: access log logs/domain2.access.log main; 


: location / { 

: index index.html; 

: root /var/www/domain2.com/htdocs; 
: 3 

: 4 

} 


虚拟 主机 标准 配置 (简化 ) - A Default Catchall Virtual Host 


ER { 

: server { 

: listen 80 default; 

: server_name pr 

: access log logs/default.access.log main; 


: location / { 

: index index.html; 

: root /var/www/default/htdocs; 
: 3 

Boy 

} 


在 父 文件 夹 中 建立 子 文件 夹 以 指向 子 域名 -Wildcard 


Subdomains in a Parent Folder 


这 是 一 个 添加 子 域名 (或 是 当 DNS 已 指 向 服务 器 时 添加 一 个 新 域名 ) 的 简 单方 法 。 需要 注意 的 
是 ， 我 已 经 将 FCGI 配 置 进 该 文件 了 。 如 果 你 只 想 使 服务 器 为 静态 文件 服务 ， 可 以 直接 将 FCGI 
BEEBE, 然后 将 默认 主页 文件 变 成 index.html。 


这 个 简单 的 方法 比 起 为 每 一 个 域名 建立 一 个 vhost.conf 配置 文件 来 讲 ， 只 需要 在 现 有 的 配置 
文件 中 增加 如 下 内 容 : 


This is just a really easy way to keep adding new subdomains, or to add new domains 
automatically when DNS records are pointed at the server. Note that | have included FCGI 
here as well. If you want to just serve static files, strip out the FCGI config and change the 
default document to index.html. Rather than creating a new vhost.conf file for every domain, 
just create one of these: 


server { 

: # Replace this port with the right one for your requirements 

: # 根据 你 的 需求 改变 此 端口 

: listen 80; #could also be 1.2.3.4:80 也 可 以 是 1.2.3.4:80 的 形式 
: # Multiple hostnames seperated by spaces. Replace these as well. 

: # 多 个 主机 名 可 以 用 空格 隔 开 ， 当 然 这 个 信息 也 是 需要 按照 你 的 需求 而 改变 的 。 

: server name star.yourdomain.com *.yourdomain.com www.*.yourdomain.com; 
: #Alternately: — * 

: # 或 者 可 以 使 用 : _ * (具体 内 容 参 见 本 维基 其 他 页 面 ) 

: root /PATH/TO/WEBROOT/$host; 

: error page 404 http://yourdomain.com/errors/404.html; 
: access log logs/star.yourdomain.com.access.1log; 

: location / { 

: root /PATH/TO/WEBROOT/$host/; 

: index index.php; 

ue 

: # serve static files directly 

: # 直接 支持 静态 文件 (从 配置 上 看 来 不 是 直接 支持 ) 

: location ~* 4.+.(jpg|jpeg|gif|css|png|js|ico|html)$ { 


: access log off; 
: expires 30d; 
: 3 


: location ~ .php$ { 

: # By all means use a different server for the fcgi processes if you need to 
: # 如 果 需 要 ， 你 可 以 为 不 同 的 FCGI 进 程 设置 不 同 的 服务 信息 

: fastcgi_pass 127.0.0.1: YOURFCGIPORTHERE ; 

: fastcgi_index index.php; 

: fastcgi_param SCRIPT_FILENAME /PATH/TO/WEBROOT/$host/$fastcgi_script_name; 


: fastcgi_param QUERY_STRING $query_string; 
: fastcgi_param REQUEST_METHOD $request_method; 
: fastcgi_param CONTENT_TYPE $content_type; 


: fastcgi_param CONTENT_LENGTH $content_length; 
: fastcgi_intercept_errors on; 

>} 

: location ~ /\.ht { 

: deny all; 

Dj 

2 


负载 均衡 


一 个 简单 的 负载 均衡 的 示例 ， 把 www.domain.com 均 衡 到 本 机 不 
同 的 端口 ， 也 可 以 改 为 均衡 到 不 同 的 地 址 上 。> 


http { 

: upstream myproject { 

: server 127.0.0.1:8000 weight=3; 
: server 127.0.0.1:8001; 

: server 127.0.0.1:8002; 

: server 127.0.0.1:8003; 

: 3 


: server { 

: listen 80; 

: server name www.domain.com; 

: location / ( 

: proxy pass http://myproject; 
} 


} 


nginxX 防 盗 链 


location -* \.(gif|jpg|png|swf|flv)$ { 

root html 

valid referers none blocked *.nginxcn.com; 

if ($invalid referer) { 

rewrite ^/ [www.nginx.cn](http://www.nginx.cn/) 
return 404; 

} 

} 


前 面 的 root 可 以 不 要 如 果 你 在 serverf} 中 有 设置 可 以 不 需要 设 定 


HWLoadbalancerCheckErrors 


Some Hardware Load-balancers such Cisco's CSS and BigIP Products test the readiness of 
the backend Machines with SYN-ACK-RST. 


This behavior causes a 400 error in nginx. 


With the GEO Module and the if-Statement you can omit these entries: 


http { 
geo $1b ( 
default 0; 
19.1.1.1/32 1; # LB IPs 


10.1.1.2/32 1; 
} 


HV... 

server { 
Ho... 
access log /path/to/log; 
error_page 400 /400; 
location = /400 { 


if ($lb) { 
access_log off; 


} 
return 400; 
} 


